Mailgun Migration Guide

Mailgun Migration Guide Overview

This Mailgun Migration Guide is for those considering a move from Mailgun to SparkPost. As with our other migration guides, we’ll walk through the account setup process and call out any differences along the way, with the goal of reducing the friction on your decision making and migration planning processes.


We’ll start with a comparison of terms:

SparkPost term Mailgun term
Sink server Test mode
Metrics Stats
Message events Events (formerly logs)
Relay webhooks Routes
Substitution data Recipient variables / template variables
Metadata, tags my-custom-data / X-Mailgun-Variables
Transmissions Messages
Suppression Lists Suppressions
Sending domains, bounce domain, tracking domains, inbound domains Domains

Where To Get Help

If you’re in a hurry, don’t have time to read this Mailgun Migration Guide and just want the gritty details, check out our DevHub, API docs and pricing. If you have general questions, take a walk through our support articles, or if you just want to chat, join our community on Slack.

Signing Up

Sign up for your SparkPost account here. On sign-up, your free developer account has a generous monthly email allowance and all service features are available.

Note: Please create only a single SparkPost account for your organization. If you need separate environments or to send on behalf of multiple clients, please use subaccounts. Both of these are explained in more detail below.

The SparkPost Dashboard

After sign-up and whenever you sign in, you’ll see your SparkPost dashboard.  Along with your daily and monthly usage reports, the dashboard includes a section named ‘Your Progress’. The steps outlined there form a useful ‘onboarding’ checklist so do take a moment to review.

SparkPost Dashboard Screenshot - Mailgun Migration Guide

Sending Your First Email

At this point, you can send email, provided you use the domain in your ‘From’ address (e.g. “From:”). Each SparkPost account has a 50-email, lifetime allowance of mail from this ‘sandbox’ domain and it’s meant as an easy exploration and testing feature. This is a little different than Mailgun which creates a “sandbox domain” for you to get started with. Mailgun also allows you to send to only 5 named recipients from your sandbox domain. SparkPost’s sandbox imposes no such limitation.

To begin sending real production emails, both Mailgun and SparkPost expect you will use a domain of your own.

If you would like to jump straight in and send your first email, check out the REST API section below.  As with Mailgun, you can also send via SMTP if you prefer.

Setting Up A Sending Domain

To begin sending mail from your own domain, you must tell SparkPost about it by adding it as a sending domain on your account. SparkPost will then check that you own it. You can create and manage your sending domains from Sending Domains in the Accounts menu.

Mailgun’s domains group sending, tracking and receiving domain configuration together. By comparison, SparkPost separates these concepts into sending, bounce, tracking, and inbound domains and each can be configured separately.

To verify your sending domain, you can opt to receive an email to the abuse@ or postmaster@ account for your domain or you can publish SPF or DKIM DNS records for it.

Note: SparkPost only requires that you complete 1 type of domain ownership verification. However, we recommend that you configure at least DKIM on your domains, as this will improve your domain’s reputation, and thus, your chances of consistently hitting the inbox.

Service Providers

If you send on behalf of multiple customers through their own sending domains, you are probably familiar with Mailgun’s per domain SMTP and API credentials. SparkPost’s analogue is its subaccounts feature, which offers separate credentials, domains, and message events along with an API for programmatic onboarding of your customers. Similar to Mailgun’s per domain config, each SparkPost subaccount gets its own API key, and each sending domain a DKIM DNS record. Your customer need only publish the DKIM key in their DNS and then use the API key to start sending email.

Important: Migrate Your Suppression List

When you use any modern email service, it will maintain a suppression list of recipients you should not send mail to; for example, people who unsubscribe from your list or complain about your messages, as well as email addresses which are invalid. It’s like your own personal “do not call” list.

When switching email providers, it’s very important to avoid sending to these addresses again to avoid incurring very high bounce and complaint rates early on. If this happens, we may even have to suspend your account to protect you and our other customers’ reputations. Migrating your suppression list from the old service into the new should be one of your first actions.

Mailgun’s suppression list collects recipients whose email has bounced, who have complained or who have unsubscribed from your communications. SparkPost’s suppression list is similar – you can manage it within SparkPost and it also includes an API endpoint for bulk uploading your suppression list.

Migrating to the SparkPost REST API

The SparkPost REST API expects JSON requests, in contrast to Mailgun’s form-data request formatting. Both respond with JSON. The most commonly used part of the SparkPost API is the transmissions endpoint, which is broadly equivalent to Mailgun’s messages endpoint since SparkPost transmissions support similar single, batch and scheduled send features.

As a side note, while many Mailgun API endpoints are scoped by sending domain, SparkPost prefers top-level API endpoints in most cases. For example, to send mail from, Mailgun might expect a call to, a SparkPost user would call

Note: Mailgun includes mailing lists for maintaining a list of recipients you regularly communicate with. The SparkPost transmissions endpoint is most often used with inline recipients rather than a stored list. SparkPost also has a recipient list capability but it is intended as a short-term cache for your recipient list and not as a database of record for your mailing lists.

You can call the SparkPost API directly using tools like Postman, cURL or HTTPie but it’s more common to use one of our official client libraries:

Our thriving developer community also maintains libraries for other languages and platforms including C# and Ruby.

Whichever tools you choose, you will need to issue yourself an API key to start using the SparkPost API. Unlike Mailgun’s credential per domain policy, you can create as many API keys as you need, each with their own privileges so you can compartmentalize access rights across your software stack and organization.

Sending Mail Over SMTP

SparkPost also accepts email over traditional SMTP – with a few modern twists. In short, you can set metadata, tags, and configuration options by including a custom header named X-MSYS-API in your messages which is roughly analogous to Mailgun’s X-Mailgun- headers. You can read the full SparkPost SMTP API reference documentation here.

Note: If you’d like to use advanced features like dynamic message generation with templates and personalization, you should use the REST API’s transmission, template and substitution capabilities.


SparkPost templates offer the same basic variable substitution capabilities that are available with Mailgun’s recipient and template variables but where Mailgun relies upon fixed key/value pairs, SparkPost substitution data supports structured recipient data. SparkPost’s templates also support logic and iteration to translate rich recipient data into customized and preference-driven email content. SparkPost can also store templates within your account for re-use and to separate content management from the API calls that trigger delivery.

It’s worth remembering that SparkPost wraps substitution variables with double braces in contrast to Mailgun’s percent delimiters. Here are a few example template snippets to show what’s possible:

  • Basic substitution: Hello {{firstName}}
  • Default values: Hello {{firstName or ‘Captain’}}
  • Conditionals: {{if == ‘cat’}} Miaow! {{else}} Woof! {{end}
  • Iteration: {{each cartItems}} {{loop_var}} {{end}}

To explore further, you can create, edit and preview your templates (using test substitution data) within SparkPost and also using the templates API endpoint.

Tracking Your Email Activity

SparkPost offers 2 levels of tracking information. The first is aggregate metrics which are a richer and more complete form of Mailgun stats – rolled up, time windowed summaries of your mailing and recipient activity. Metrics are viewable as customizable time series graphs and also available programmatically using our metrics API endpoint. The second level of tracking information exposes the more fine-grained individual activity used to build our aggregate metrics. This individual activity is also available two ways – through our message events interface, or by making use of our message events API endpoint and webhooks features which let you process the data however you like.


Your SparkPost account includes an extensive set of metrics for tracking your email activity. You can review summary reports, a breakdown of bounces and engagement (our term for opens and clicks), and more. All of these reports can be narrowed by time window and are calculated down to the minute. If you choose to set a campaign ID on your transmissions, metrics can also be filtered using those campaign ID values and by other fields such as recipient domain and IP pool. See the documentation linked above for a complete list of querying and filtering capabilities.

All SparkPost metrics are stored on your account for 6 months.

Message Events and Webhooks

SparkPost’s message events API endpoint provides similar functionality (and then some!) to Mailgun’s events capability: the message events report is a searchable view of the last 10 days of events on your account. Those events are available in pull fashion by querying the message events endpoint directly and in push fashion if you use the webhooks facility.

Where Mailgun supports a single webhook per domain and event type, one may create as many SparkPost webhooks as required, each filtered to receive one or more types of events.

Here’s a mapping of each Mailgun event to its SparkPost message event equivalent(s):

Mailgun event SparkPost event
accepted injection
rejected policy_rejection, generation_rejection
delivered delivery
failed bounce, out_of_band
opened open
clicked click
unsubscribed list_unsubscribe, link_unsubscribe
complained spam_complaint

Events Specifications

The SparkPost API includes embedded JSON specifications and sample event generation services for both message events and webhooks.


SparkPost provides metadata and tag facilities for labelling your email activity with information from your application, similar to Mailgun’s my-custom-data API field and X-Mailgun-Variables SMTP header.

You can provide metadata with your transmissions, both at the request level and for each individual recipient, with recipient metadata overriding the top-level values. As with Mailgun, any metadata you provide at message send time will later be available in all events relating to that message, both through message events and webhooks.

Note: If you use SMTP, metadata and tags can also be set using the X-MSYS-API message header.

Inbound Email

SparkPost’s relay webhooks process and forward email addressed to an HTTP endpoint you control, much like using Mailgun’s routes mechanism and its forward() action. Each relay webhook accepts SMTP traffic on your behalf, and forwards JSON-encoded messages to you over HTTP. SparkPost’s relay webhooks are conceptually simpler than Mailgun’s routes in that any matching, filtering or storage must take place in your HTTP service.

Note: SparkPost requires that you register your inbound domain before you can receive inbound mail through a relay webhook.

If you have general questions not addressed in this Mailgun Migration Guide, feedback or want to chat about your particular situation, come find us on Slack! If you have an issue with your SparkPost account, you can check out our support articles here and contact our Support team directly here.

Get Started Today!

Try SparkPost and see how we deliver far more value than the competition.