Email APIs: Definition, benefits, and how they work

Are you creating an e-commerce web page that needs to send transactional emails to customers? A developer building a web application that needs to send messages to email lists? An email marketer tasked with reaching tens of thousands of clients through targeted, personalized email blasts? Or a manager who needs an automated performance report to see how your email marketing campaigns are going?

If you’re any of the above, you need an email API.

Email APIs are a big part of what we do here at Mailgun. So, we wanted to take the time to demystify them for you. In this article, we’ll start with the basics of what an email API is and its benefits. Then, we’ll look at the difference between using SMTP and an email API to send your bulk or transactional emails, and go through some examples from our Mailgun API to demonstrate how email APIs can boost your workflow.

Let’s get started.

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 Mailgun’s email API 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.

An email marketing API is a specific type of email API designed to manage and automate marketing campaigns programmatically. It allows you to send emails for promotions, newsletters, and triggered automations directly from your application or software. It also provides tools to manage subscriber lists, personalize content, and get detailed analytics on campaign performance. 

There are many benefits to using an email API in terms of efficiency, security, and scalability. 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 some of the benefits:

• Improve deliverability: Email APIs are built on robust infrastructure and adhere to best practices that help your messages reach the intended inboxes. By automatically handling bounces and unsubscribes, the API ensures your lists remain clean, which signals to email service providers (ESPs) that you are a reputable sender and reduces the likelihood of being flagged as spam. 

• Enhance efficiency and automation: The API eliminates the need for manual, time-consuming tasks like creating and sending individual emails. This is particularly crucial for transactional emails (password resets, order confirmations) and large-scale marketing campaigns.  

• Boost personalization and engagement: Email APIs can integrate with your customer data to dynamically personalize the content of each message. This capability allows you to send highly relevant emails that can lead to higher open rates, click-through rates, and a stronger connection with your customers. 

• Real-time analytics and insights: 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. This real-time feedback loop allows you to make data-driven decisions and optimize your email campaigns for better results. 

• Ensure data security and compliance: Protect your business and your customers with advanced security protocols. Email marketing APIs use secure authentication and encryption to safeguard sensitive customer data.  

• Enable event-driven automation: Create webhooks that send email event data to a CRM. Use webhooks to send your event 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, allowing you to program a follow-up action, like sending out a password reset email. 

• Scalability: When using SMTP for email sending, consider both 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 

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.

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:

                            

                                v3/<domain>/messages
                            
                        

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:

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:

                            

                                curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
    -F from='Excited User <mailgun@YOUR_DOMAIN_NAME>' \
    -F to=foo@example.com \
    -F to=bar@example.com \
    -F subject='Hello' \
    -F text='Testing some Mailgun awesomeness!'
                            
                        

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!”

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:

                            

                                {
  "message": "Queued. Thank you.",
  "id": "<20111114174239.25659.5817@samples.mailgun.org>"
}
                            
                        

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.

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:

                            

                                curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
    -F from='Excited User <YOU@YOUR_DOMAIN_NAME>' \
    -F to='foo@example.com' \
    -F cc='bar@example.com' \
    -F bcc='baz@example.com' \
    -F subject='Hello' \
    -F text='Testing some Mailgun awesomeness!' \
    --form-string html='<html>HTML version of the body</html>' \
    -F attachment=@files/cartman.jpg \
    -F attachment=@files/cartman.png
                            
                        

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 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:

                            

                                {
  "message": "Queued. Thank you.",
  "id": "<20111114174239.25659.5817@samples.mailgun.org>"
}
                            
                        

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

                            

                                curl --user 'api:PRIVATE_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate \
    --data-urlencode address='foo@mailgun.net'
                            
                        

We should get the following response to our API call:

                            

                                {
    "address": "foo@mailgun.net",
    "is_disposable_address": false,
    "is_role_address": false,
    "reason": [],
    "result": "deliverable",
    "risk": "low"
}
                            
                        

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

                            

                                curl -s --user 'api:YOUR_API_KEY' -X POST \
      https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/templates \
      -F name="billing" 
      -F description="template description"
      -F tag="v0" 
      -F template="template contents"
                            
                        

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:

                            

                                {
  "template": {
      "createdAt": "Wed, 29 Aug 2021 23:31:13 UTC",
      "description": "template description",
      "name": "billing",
      "version": {
          "createdAt": "Wed, 29 Aug 2021 23:31:14 UTC",
          "tag": "v0",
      }
  },
  "message": "template has been stored"
}
                            
                        

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).

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.

Author: Mary Dolan Mary Dolan is a former Community Marketing Manager and Copywriter at Sinch Mailgun. She was our social media guru and community leader. She was dialed into the email network and writes about the email topics and trends you're probably talking about.