Mailjet Migration Guide

This guide is here to help make your move from Mailjet to SparkPost as straightforward as possible. We'll cover the setup process, explain the equivalent terminology, and call out any differences.

Here is a quick table with the similar terms between the two services:

If you're ready for 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. You can also open a ticket with our support team.

Sign up for your SparkPost or SparkPost EU account.

Note: Please create only a single account of each type 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.

At this point, you can send email immediately provided you use the sparkpostbox.com domain in your 'From' address (e.g. "From: something@sparkpostbox.com"). Each SparkPost account has a 5-email, lifetime allowance of mail from this 'sandbox' domain and it's meant as an easy exploration and testing feature. To begin sending real production emails, both Mailjet 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. You can also send via SMTP if you prefer.

Terminology: MJ: sender address -- SP: sending domain

To begin sending mail from your own domain, you need to register it with SparkPost. You can create and manage your sending domains from Sending Domains (EU) page.

Verify your sending domain by publishing DKIM DNS records or verify via any email address. Once you add a sending domain with SparkPost, you can send from any localpart with that domain like if you added *@example.com as a sender address in Mailjet.

Once a domain is verified, you are able to send from any address from that domain.

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

Terminology: MJ: Exclusion list -- SP: Suppression list

When you use any modern email service, it will maintain a list of addresses you shouldn't send mail to. For example, you should avoid sending emails to anyone who has unsubscribed or reported a message of yours as spam. It's like your own personal "do not call" list.

When switching email providers it is important to avoid sending to these addresses again to avoid incurring very high bounce and complaint rates early on. Migrating your suppression list from your old service into the new should be one of your first actions.

Mailjet collects a list of address who you should avoid sending in your exclusion list. Be sure to download this from Mailjet and upload it through the SparkPost app (EU) or via the API.

*Terminology: MJ: Message -- SP: Transmission
*Terminology: MJ:  Contacts/Recipients -- SP: Recipients

The SparkPost transmissions endpoint is broadly equivalent to the Mailjet v3 Send API.  Each transmission call should have either inline content or a template and one or more recipients which can have substitution data and metadata for tracking.

While you can directly call the API via tools like Postman, cURL, or HTTPie, it's more common to use one of our official client or community libraries:

• php-sparkpost
• python-sparkpost
• node-sparkpost
• java-sparkpost
• go-sparkpost
• elixir-sparkpost
• C#
• Ruby

Regardless of the tool you use, you need a API key (EU) to use the SparkPost API. With Mailjet you need both a public and a private key -- with SparkPost you use a single key. You can create as many keys as you need, each with their own privileges so you can compartmentalize access rights across your software stack and organization.

SparkPost also accepts email over traditional SMTP -- with a few modern twists. To authenticate, set the SMTP password to a SparkPost API key with "Send via SMTP" permissions. 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 Mailjet's X-MAILJET- and X-MJ- 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 variable substitution capabilities, conditional blocks, structured data, and loops that are available with Mailjet's template language. Where Mailjet uses both double curly braces and curly braces with percent signs for different blocks, SparkPost only uses double curly braces. SparkPost can also store templates within your account for re-use and to separate content management from the API calls that trigger delivery.

Here are a few example template snippets to show what's possible:

• Basic substitution: Hello {{firstName}}
• Default values: Hello {{firstName or 'Captain'}}
• Conditionals: {{if pet.species.name == '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 (EU) or using the templates API endpoint.

SparkPost offers 2 levels of tracking information. The first is aggregate metrics which are broadly equivalent to Mailjets key performance statistics -- rolled-up, time-windowed summaries of your activity. These are viewable as customizable time series graphs (EU) and also are available programmatically using the 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 the message events (EU) page, or through the message events API endpoint and webhooks 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 (EU), a breakdown of bounces (EU) and engagement (EU) (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.

SparkPost stores all your metrics for 6 months.

SparkPost's message events API endpoint provides similar functionality Mailjet's event and statistics API endpoints. The message events API is a searchable list of the last 10 days of events of all types. Those events are available in pull fashion by querying the message events endpoint directly and in push fashion if you use the webhooks feature, like the Mailjet's event callback url. For app integrations we recommend webhooks since they offer resilient, low latency, near-real-time access to events as they happen.

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

Terminology: MJ: Parse Webhook -- SP: Relay Webhook

SparkPost's relay webhooks process and forward email addressed to an HTTP endpoint you control, much like using Mailjet's Parse API. Unlike Mailjet, SparkPost offers this feature on the free tier. Each relay webhook accepts SMTP traffic on your behalf, and forwards JSON-encoded messages to you over HTTP.

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