Everything you need to know about sending email with APIs

What is an email API?

An Application Programming Interface (API) is a mechanism that allows two applications to talk to one another, and gives different platforms the ability to access one another’s resources without compromising security or control.

An email API is a specific type of API that you can use to connect your web app or platform to an Email Service Provider (ESP) to use its capabilities within your own app's workspace. This means that instead of navigating to the ESP separately to send your marketing email blast, you can now use an email API to programmatically send messages within your app.

Here’s a breakdown of how it works:

1. Mailgun’s Email API allows you to integrate your app with Mailgun, an email service provider that focuses on getting your mail delivered.

2. From your app, you can use an API request to send your email messages. This API request is labeled “HTTP” above. We’ll go over why below when we discuss how APIs work.

3. Mailgun receives your email sending request and compiles it before adding to the queue. Transactional email service providers like Mailgun help streamline your email efforts by providing troubleshooting, status logs, storage solutions, response handling, email analytics, and optimized delivery.

4. Then, Mailgun delivers your message via API or Simple Mail Transfer Protocol (SMTP) to your subscribers’ email clients, like Microsoft Outlook, AOL, Gmail, or Yahoo. We’ll go into more detail about SMTP below.

5. Your subscribers’ email clients then deliver the messages to their inboxes.

What can an email API do?

There are many benefits to using an API in terms of efficiency, security, and scalability. One of the best examples is transactional emails. Email APIs can deliver emails as an immediate consequence of specific user actions like:

• Email account confirmation emails

• Password resets

• Purchase order confirmations

• Digital receipts

With the API you are able to set triggers and create and send email templates that can be customized to an individual user based on their name, purchase, or other actions.

The API isn’t limited just to transactional emails. The benefits of any API relate to streamlining processes without compromising security – and you retain the benefit of operating services from within your own environment. This makes it much easier to pull metrics and oversee reporting. Here are a few more examples:

• Get email analytics to track metrics and assess your email campaigns. Use an email API to pull and compile deliverability metrics like open-rate, how many subscribers clicked your Call-to-Action (CTA) button, or how many emails resulted in conversions.

• Create webhooks that send email event data to a CRM. Use webhooks to send your events data to external Customer Relationship Management (CRM) tools. You can use email APIs to create webhooks that notify you when a specific event has happened, like a subscriber requesting a password reset, so you can program a follow-up action, like sending out a password reset email.

• Operate at scale. If you use SMTP to send email, you need to take into account your sending volume and security. If your normal sending volume spikes, email clients might flag your behavior as spammy. With API calls that go through cloud servers, you don’t have the same issues when operating at scale. Additionally, SMTP doesn’t automatically come with the ability to build in layers of authentication, we break down API vs SMTP more here.

How does an email API work?

Okay, so now we know what an email API does and the benefits of using one. But how does it work? We won’t go into all the nitty-gritty of APIs, but we can show you the big picture. We’ll start with the architecture of an API. Then, we’ll discuss the requests you can make to an API and the responses you’ll receive.

What is API architecture?

Email APIs like Mailgun’s API conform to a modern convention called REST (REpresentational State Transfer), an API architectural style that centers around manipulating resources. These resources are data objects like text files, HTML pages, or datasets.

You can issue requests to access or modify these resources through Unique Resource Indicator (URI) endpoints. URIs are similar to URLs, but they are only able to identify a resource, whereas URLs locate the resource.

For example, this is the email sending endpoint of Mailgun’s Email API:

You can send requests to this endpoint to send out emails.

RESTful APIs use endpoints to manage resources and allows the user to create, read, update, and delete records by communicating with those enpoints.

These are some of the popular Mailgun enpoints:

What kind of requests can I send via the API?

When using an API, you manage and update by issuing requests:

• POST creates a new resource

• GET requests a resource

• PUT replaces a resource

• PATCH updates a resource

• DELETE deletes a resource

These requests use standard Hypertext Transfer Protocol (HTTP) methods. Sometimes, you’ll see the terms “send an HTTP request” instead of “sending a request via the API” like in the Mailgun API image above. They mean the same thing.

Here’s an example of a POST request sent to the Messages endpoint of Mailgun’s Email API:

This request tells the API to send a plaintext email from Excited User at mailgun@YOUR_DOMAIN_NAME to foo@example.com and bar@example.com. The email has a subject line “Hello” and contains the message, “Testing some Mailgun awesomeness!”

What is an API response?

There’s nothing worse than shooting off emails or lines of code into the dark, right? That’s why depending on the type of HTTP request you sent, you’ll get a specific type of response back. The response will either be the requested data (like a stored email message that you want to retrieve) or a confirmation that the requested action was performed. Responses are formatted as XML, JSON, YAML, or other formats. For instance, Mailgun returns JSON responses.

For instance, here’s the JSON response you should receive from the Mailgun API if the POST request above was correctly sent:

What are some email API use case examples from Mailgun?

At Mailgun, we believe that ease and efficiency are key to a good email experience. You can use the Mailgun API with programming languages and frameworks like Node.js, curl, Python, PHP, Microsoft.NET, Java, and more. Check out our libraries to get started.

Here are some use cases for our Email APIs:

• Use our Sending API to send an HTML email effortlessly and at scale.

• Use our email validations API to verify an email address.

• Use our Templates API to create, upload, store, and version an HTML email template.

Let’s go into more detail for each of these below.

How can I use Mailgun’s Sending API to send an HTML email?

Use a POST request to send an HTML email with attachments via Mailgun’s Sending API to send.

We’ll start with the following code:

In the example above, we’ve sent a message from Excited User at YOU@YOUR_DOMAIN_NAME to three recipients: foo@example.com, bar@example.com, and baz@example.com. We’ve attached the HTML email content by pasting it directly in between the <html> tags. We’ve also added two attachments: cartman.jpg and cartman.png.

You’ll need to substitute YOUR_API_KEY with your own API key. Also keep in mind, if you’re an EU user, please use the base URL for our EU environment: https://api.eu.mailgun.net/.

We should receive the following response for our API call:

How can I use Mailgun’s email validations API to verify an email address?

Let’s continue onto another use case. We’ll use a GET request to validate an email address via the email validations API:

We should get the following response to our API call:

How can I use Mailgun’s Templates API to upload an HTML email template?

For our final use case, let’s try storing a template by issuing a POST request via the Templates API:

In this request, the name parameter indicates the template name. This is used to reference the template in other API calls. The tag parameter identifies the specific version of this template. The template parameter specifies the template content itself. Here, you can paste the template’s HTML content directly into the request.

We should receive the following response:

Email APIs help improve deliverability

Email APIs help in email deliverability by making messaging easier for both senders and recipients. An API ensures that a message is sent to a predetermined audience – usually through a list created by the sender – and eliminates the need for large numbers of time-consuming, manually generated messages.

The reduction of manual sending also ensures there are fewer human errors, like mistyped email addresses or emails not going out when they need to. This improves the accuracy and consistency of sent email messages and leads to stronger levels of engagement with the targeted audience.

The role of APIs in improving deliverability and engagement is particularly important for organizations that communicate with large audiences. If one hundred customers request account password resets from a company in the span of an hour, that demand would be almost impossible to fill if the company attempted to manually create one hundred emails for its customers (think of the chocolate factory episode of I Love Lucy).

Ready to send?

APIs are not always easy to wrap your brain around but they make your email program more reliable and more efficient. Want more information on how Mailgun’s email APIs can help you? Check out our API documentation or connect with our deliverability experts.