Email API Migration Guide: Mailgun to Elastic Email

by Ula Chwesiuk | Jun 4, 2024

Changing your email API provider can be swift and hassle-free. Using the example of switching from Mailgun to Elastic Email, we've put together an email API migration guide for you. You will find all the information you need to start using our platform - differences in terminology, our resources, libraries, documentation, and how to integrate with our email API step-by-step.

Table of Contents

TL;DR
API libraries
How to get started
Email API Migration guide: wrapping up
FAQ

TL;DR

Migrating from Mailgun to Elastic Email takes four changes to your sending code and no downtime. Swap Mailgun's HTTP Basic auth (api:YOUR_API_KEY) for Elastic Email's X-ElasticEmail-ApiKey header, point requests at https://api.elasticemail.com/v4, drop the /{domain_name}/ segment from your paths because Elastic Email endpoints are account-scoped, and map POST /v3/{domain_name}/messages to POST /v4/emails/transactional. Run both providers in parallel while you shift traffic.

Sign up for a free Elastic Email account - 3,000 emails per month, no credit card.
Verify your sending domain by adding Elastic Email's SPF and DKIM records alongside your existing Mailgun records.
Create an API key in the app (up to 15 per account) and install one of the 12 official libraries.
Map your endpoints using the table below, then move suppressions, templates and contacts across.
Cut over gradually - send a share of traffic through Elastic Email, confirm delivery, then switch the rest.

API libraries

We have prepared and constantly maintain API libraries for various programming languages and frameworks. Our downloadable libraries are often accompanied by guides for authentication, code samples, and other useful resources. We currently have libraries for 12 languages:

If you cannot find the library you’re looking for, let us know at contact@elasticemail.com.

How to get started

Let us walk you through all the steps you need to take to set up your Elastic Email account, integrate with our email API, and start sending emails.
We also prepared comprehensive API documentation so that you can integrate with our email API and use it according to your sending needs. Looking at API documentation is the best way to see the difference between email service providers. To simplify matters, we prepared a comparison of the most essential API references for both Elastic Email and Mailgun:

API Name
Introduction	Introduction	Get Started
Authentication	Authentication	Authentication
Sending Emails	Emails	Messages
Managing Suppressions	Suppressions	Bounces
Managing Templates	Templates	Templates
Email Lists	Lists	Mailing Lists
Inbound Email Processing	Inbound Route	Routes
Events	Events	Events
Statistics	Statistics	Stats

Signing up

To get started, sign up for an Elastic Email account. Choose the Email API product and create your account for free. No credit card details are required. You will then receive a confirmation email to verify your profile.

Setting up a sending domain

Once you created your Elastic Email account, it’s time to add your sending domain and verify it by adding the DNS settings. Check out our help article to learn how to verify your domain step-by-step, or watch our guide video below:

Creating your API Key

To provide valid authentication and start using our API, you will need an API key. To generate your API key, enter settings on your Elastic Email account and go to Settings -> Manage API Keys -> Create.

At this point, you can set custom permissions and optional access for your API key.

Once you create your API key, keep it safe as it will be used for every API call you make in order to identify you and confirm your account’s credentials. You can create up to 15 API keys.

Your API key should be sent inside the header with the parameter name ‘x-elasticemail-apikey’ and your API key as a value.

Installing API library

To start sending emails via our email API, we highly recommend downloading a repository of the programming language you use and installing it. Both Mailgun and Elastic Email have a rich selection of email API libraries and SDKs of many programming languages. It will make the migration process very easy and convenient for you. Just as with Mailgun's email API integration you installed a library or SDK, you need to do the same with Elastic Email. Remember that all our downloadable repositories are available on Github.

Let’s show you the installation process using JavaScript. For example, when you want to install the repository for Node.js.

Npm

To publish the library via npm, please follow the procedure in "Publishing npm packages".

Then install it via:

npm install @elasticemail/elasticemail-client --save

npm install @elasticemail/elasticemail-client --save

Sending your first email

Let us first take a look at what sending an email via Mailgun API looks like:

const formData = require('form-data');
  const Mailgun = require('mailgun.js');
  const mailgun = new Mailgun(formData);
  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
mg.messages.create('sandbox-123.mailgun.org', {
    from: "Excited User &lt;mailgun@sandbox-123.mailgun.org&gt;",
    to: ["test@example.com"],
    subject: "Hello",
    text: "Testing some Mailgun awesomness!",
    html: "&lt;h1&gt;Testing some Mailgun awesomness!&lt;/h1&gt;"
  })
  .then(msg =&gt; console.log(msg)) // logs response data
  .catch(err =&gt; console.error(err)); // logs any error

const formData = require('form-data');
  const Mailgun = require('mailgun.js');
  const mailgun = new Mailgun(formData);
  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
mg.messages.create('sandbox-123.mailgun.org', {
    from: "Excited User <mailgun@sandbox-123.mailgun.org>",
    to: ["test@example.com"],
    subject: "Hello",
    text: "Testing some Mailgun awesomness!",
    html: "<h1>Testing some Mailgun awesomness!</h1>"
  })
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error

If you want to send your first email via Elastic Email, you need to load the library, get client instance, use your newly generated Elastic Email API key, and create an instance of EmailsApi that will be used to send the email. The 'key-yourkeyhere' for the API key in Mailgun is now replaced by "YOUR_API_KEY".

Based on the JavaScript example, here’s the whole code for sending an email to copy and paste:

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const emailsApi = new ElasticEmail.EmailsApi();
const emailData = {
    Recipients: [
        {
            Email: "johnsmith@domain.com",
            Fields: {
                name: "John"
            }
        }
    ],
    Content: {
        Body: [
            {
                ContentType: "HTML",
                Charset: "utf-8",
                Content: "&lt;strong&gt;Hi {name}!&lt;strong&gt;"
            },
            {
                ContentType: "PlainText",
                Charset: "utf-8",
                Content: "Hi {name}!"
            }
        ],
        From: "myemail@domain.com",
        Subject: "Example email"
    }
};

const callback = (error, data, response) =&gt; {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Email sent.');
    }
};
emailsApi.emailsPost(emailData, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const emailsApi = new ElasticEmail.EmailsApi();
const emailData = {
    Recipients: [
        {
            Email: "johnsmith@domain.com",
            Fields: {
                name: "John"
            }
        }
    ],
    Content: {
        Body: [
            {
                ContentType: "HTML",
                Charset: "utf-8",
                Content: "<strong>Hi {name}!<strong>"
            },
            {
                ContentType: "PlainText",
                Charset: "utf-8",
                Content: "Hi {name}!"
            }
        ],
        From: "myemail@domain.com",
        Subject: "Example email"
    }
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Email sent.');
    }
};
emailsApi.emailsPost(emailData, callback);

Email API Migration guide: wrapping up

We hope you are now equipped with all the essential information and resources you need to migrate to our email API. If you have any questions or need additional assistance, our customer support expert will be happy to help you from day one. They are available to you 24/7 via email at support@elasticemail.com or via live chat, which you can find in the bottom right corner of our website and platform.
Haven’t you signed up for an Elastic Email account? Try it out and start sending emails with us today!

Enjoying this Content?

You can receive articles like this straight to your inbox.
Sign up for our newsletter and get a dose of email marketing knowledge every month!

FAQ

Not as a drop-in replacement, but the changes are small and mechanical. You replace Mailgun's HTTP Basic auth with the X-ElasticEmail-ApiKey header, change the base URL to https://api.elasticemail.com/v4, remove the /{domain_name}/ segment from your paths, and restructure the send payload into Elastic Email's Recipients and Content objects. Most integrations are a single afternoon's work. Using one of the 12 official libraries removes the request-building work entirely.

Export each suppression type from Mailgun with GET /v3/{domain_name}/bounces, GET /v3/{domain_name}/complaints and GET /v3/{domain_name}/unsubscribes, then post the addresses to POST /v4/suppressions/bounces in Elastic Email. Do this before your first production send - sending to addresses that already bounced on Mailgun is the fastest way to damage the reputation of a new sending setup.

Yes. Elastic Email issues its own SPF and DKIM records, which you add to your DNS alongside the Mailgun records you already have. Both providers can authenticate the same domain at the same time, so nothing breaks while you are testing. Once all your traffic is on Elastic Email you can remove the Mailgun records.

There does not need to be. Because both providers can be authenticated for the same domain simultaneously, the safe pattern is to run them in parallel: keep Mailgun live, route a small share of traffic through Elastic Email, confirm delivery and event data look right, then increase the share until Mailgun is idle. No cutover moment, no queue to drain.

If you move to a dedicated IP, yes - mailbox providers judge a new IP on its own history, so ramp volume gradually over the first few weeks rather than moving your full send in one day. On shared IPs the pool already has an established reputation and no warm-up is needed. The gradual parallel-run cutover described above doubles as a warm-up schedule.

Yes. The free plan covers up to 3,000 emails per month and 1,000 contacts with no credit card required, which is enough to build and test your integration end to end before you move production traffic. Paid plans start at $19 per month for the Starter plan; inbound processing, webhooks and reseller features are on the Pro plan at $49 per month.

The API allows 20 concurrent connections with a 600-second request timeout, and the maximum size of a single message including attachments is 20 MB. Each account can hold up to 15 API keys, which you can create and rotate through the app or with the /v4/security/apikeys endpoints.

Twelve, all actively maintained with code samples: Python, PHP, JavaScript, TypeScript Angular, TypeScript Axios, Java, C#, Go, Ruby, Rust, Perl and Bash. If your language is not on the list, you can integrate directly with the REST API. It is a standard JSON over HTTPS interface.

Yes. Mailgun's /v3/routes maps to Elastic Email's /v4/inboundroute, with the same create, read, update and delete operations. Inbound email processing is available on the Pro plan.

If you like this article, share it with friends:

Ula Chwesiuk

Ula is a content creator at Elastic Email. She is passionate about marketing, creative writing and language learning. Outside of work, Ula likes to travel, try new recipes and go to concerts.

Beyond the Free Trial: 5 Hidden Costs of Choosing the Wrong Email Service Provider

Elastic Email API as a Great SendGrid Alternative

Elastic Email vs. SMTP2GO: Why Elastic Email Is the Smarter SMTP2GO Alternative

Eager to put this knowledge to some use?

Try one of our products!

Try for Free

See pricing

Email API Migration Guide: Mailgun to Elastic Email

TL;DR

API libraries

How to get started

API Name

Introduction

Authentication

Sending Emails

Managing Suppressions

Managing Templates

Email Lists

Inbound Email Processing

Events

Statistics

Signing up

Setting up a sending domain

Creating your API Key

Installing API library

Npm

Sending your first email

Email API Migration guide: wrapping up

FAQ

Can I keep my existing Mailgun code after switching to Elastic Email?

How do I move my Mailgun suppression list to Elastic Email?

Do I need to re-verify my sending domain when I migrate?

Will there be downtime or lost email during the migration?

Should I warm up a new IP when I switch from Mailgun?

Does Elastic Email have a free plan for testing the migration?

What are Elastic Email's API limits?

Which programming languages have official Elastic Email libraries?

Does Elastic Email support inbound email like Mailgun Routes?