Everything you need to know about sending email with APIs

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

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.

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.