diff --git a/components/site/docsHomePageContent.tsx b/components/site/docsHomePageContent.tsx index f6b82bac0..6e88efa86 100644 --- a/components/site/docsHomePageContent.tsx +++ b/components/site/docsHomePageContent.tsx @@ -7,10 +7,10 @@ import BaseHomePageContent, { SimpleStyledLink } from './baseHomePageContent'; /* ██████╗ ██████╗ ███╗ ██╗████████╗███████╗███╗ ██╗████████╗ ██╔════╝██╔═══██╗████╗ ██║╚══██╔══╝██╔════╝████╗ ██║╚══██╔══╝ -██║ ██║ ██║██╔██╗ ██║ ██║ █████╗ ██╔██╗ ██║ ██║ -██║ ██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██║╚██╗██║ ██║ -╚██████╗╚██████╔╝██║ ╚████║ ██║ ███████╗██║ ╚████║ ██║ - ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ +██║ ██║ ██║██╔██╗ ██║ ██║ █████╗ ██╔██╗ ██║ ██║ +██║ ██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██║╚██╗██║ ██║ +╚██████╗╚██████╔╝██║ ╚████║ ██║ ███████╗██║ ╚████║ ██║ + ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ */ const gettingStarted = { @@ -44,14 +44,14 @@ const migrationGuides = { content: [ { text: 'SendGrid Migration Guide', - url: 'https://www.sparkpost.com/migration-guides/sendgrid/', + url: '/docs/user-guide/migrating-from-sendgrid', }, { text: 'Mandrill Migration Guide', - url: 'https://www.sparkpost.com/migration-guides/mandrill/', + url: '/docs/user-guide/mandrill-migration-guide', }, - { text: 'Mailgun Migration Guide', url: 'https://www.sparkpost.com/migration-guides/mailgun/' }, - { text: 'Mailjet Migration Guide', url: 'https://www.sparkpost.com/migration-guides/mailjet/' }, + { text: 'Mailgun Migration Guide', url: '/docs/user-guide/mailgun-migration-guide' }, + { text: 'Mailjet Migration Guide', url: '/docs/user-guide/mailjet-migration-guide' }, ], }; diff --git a/content/docs/user-guide/mailgun-migration-guide.md b/content/docs/user-guide/mailgun-migration-guide.md new file mode 100644 index 000000000..05619a39f --- /dev/null +++ b/content/docs/user-guide/mailgun-migration-guide.md @@ -0,0 +1,313 @@ +--- +lastUpdated: "02/08/2020" +title: "Mailgun Migration Guide" +description: "This Mailgun Migration Guide provides everything you need to know to migrate your email services from Mailgun to SparkPost." +--- + +Mailgun Migration Guide Overview +-------------------------------- + +This Mailgun Migration Guide is for those considering a move from Mailgun (now part of PathWire) 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. + +Terminology +----------- + +We'll start with a comparison of terms: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SparkPost termMailgun term
Sink serverTest mode
MetricsStats
EventsEvents (Logs)
Inbound Relay webhooksRoutes
Substitution dataRecipient variables / template variables
Metadata, tagsmy-custom-data / X-Mailgun-Variables
TransmissionsMessages
Suppression ListsSuppressions
Sending domain, bounce domain, tracking domain, inbound domainCustom Domain
Recipient ValidationValidations
Health Score
Spam Trap Monitoring
Engagement Recency
Deliverability Metrics: Inbox Folder and Spam Folder metrics
+(coming soon).		Inbox Placement
+ +Where to get help +----------------- + +If you're in a hurry, don't have time to read this guide and just want the details, check out our [DevHub](https://developers.sparkpost.com/), [API docs](https://developers.sparkpost.com/api) and [pricing](https://www.sparkpost.com/pricing/). If you have general questions, [take a walk through our support articles](https://www.sparkpost.com/docs/). If you need help, you can open a support ticket [directly from the SparkPost app](https://www.sparkpost.com/docs/faq/submit-a-ticket/). If you want to chat to other developers using SparkPost, [join our community on Slack](http://slack.sparkpost.com/). + +Signing Up +---------- + +Sign up for your SparkPost account [here.](https://app.sparkpost.com/join) You can choose the default US-hosted service, or select the EU-hosted service ([more info here](https://www.sparkpost.com/docs/faq/sparkpost-eu-faq/)). On sign-up, your free developer account has a monthly email allowance. You can open both account types if you wish. + +If you need separate environments or to send on behalf of multiple clients, you can use subaccounts under a single primary account. This is explained in more detail below. + +#### The SparkPost Dashboard + +After sign-up and whenever you [sign in](https://app.sparkpost.com/dashboard), you'll see your SparkPost dashboard.  This shows a Summary Report of your sending. You can easily customize the reports in SparkPost, and select your own report to be displayed here. + +![](media/mailgun-migration-guide/migration-guide-sparkpost-dashboard.png) + +Under the chart are helpful shortcuts, links to documentation and direct access to open a ticket with our Support Team. On the right, you'll see your account details and billing / usage, with a link to more detail. Below this are your configured alerts that have recently triggered. + +Sending Your First Email +------------------------ + +At this point, you can send email, using the sparkpostbox.com domain in your 'From' address (e.g. "From: something@sparkpostbox.com"). Each SparkPost account has a [small lifetime allowance](https://developers.sparkpost.com/api/transmissions/#header-the-sandbox-domain) of mail from this 'sandbox' domain. This is a little different than Mailgun which creates a "sandbox domain" for you to get started with. + +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](https://www.sparkpost.com/migration-guides/mailgun/#migrating-to-the-rest-api) below.  As with Mailgun, you can also send via [SMTP](https://www.sparkpost.com/migration-guides/mailgun/#sending-mail-over-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 a sending domain on your account. SparkPost will then check that you own it. You create and manage this from the [Domains](https://app.sparkpost.com/domains/list/sending) menu. + +Mailgun's "Custom Domains" group sending, tracking and receiving domain configuration together. SparkPost also provides [sending](https://developers.sparkpost.com/api/sending-domains.html), [bounce](https://developers.sparkpost.com/api/sending-domains/#header-using-a-sending-domain-as-a-bounce-domain), [tracking](https://developers.sparkpost.com/api/tracking-domains.html), and [inbound](https://developers.sparkpost.com/api/inbound-domains.html) domains; our [Getting Started guide](https://www.sparkpost.com/docs/getting-started/getting-started-sparkpost/) walks you through setting these up via the app. + +To verify a sending domain, you publish a DKIM DNS record. If this is not possible, you can opt to receive an email to the abuse@ or postmaster@ account for your domain. + +*Note: SparkPost only requires that you complete one 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.* + +The "Custom Domain" screen in Mailgun asks you to create a set of related DKIM, SPF and MX records for sending. With SparkPost, you create a DKIM (TXT record) and an optional bounce domain (CNAME record). SparkPost ensures custom domain [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework) authentication via the CNAME. With SparkPost, MX records are not required for sending; they're needed only if you use Inbound Relay Webhooks. + +### 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](https://app.sparkpost.com/lists/suppressions) and it also includes an [API endpoint for bulk uploading](https://developers.sparkpost.com/api/suppression-list.html#suppression-list-bulk-insert-update) 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](https://developers.sparkpost.com/api/transmissions.html), 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 example.com, Mailgun might expect a call to `https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages`, a SparkPost user would call `https://api.sparkpost.com/api/v1/transmissions.` + +*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](https://developers.sparkpost.com/api/#header-postman), [cURL](https://curl.haxx.se/) or [HTTPie](https://httpie.org/) but it's more common to make HTTPS requests from your own programming language -- see our [developer hub](https://developers.sparkpost.com/) for example code and libraries. If you're not writing your own code, see our [Marketing Campaign partner solutions](https://www.sparkpost.com/partner-category/marketing-campaigns/). + +Whichever tools you choose, you will need to [issue yourself an API key](https://www.sparkpost.com/docs/getting-started/create-api-keys/) 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](https://developers.sparkpost.com/api/smtp-api.html). + +*Note: If you'd like to use advanced features like dynamic message generation with templates and personalization, you should use the REST APIs [transmission](http://developers.sparkpost.com/api/transmissions.html), [template](https://developers.sparkpost.com/api/templates.html) and [substitution](https://developers.sparkpost.com/api/substitutions-reference.html) capabilities.* + +Templates +--------- + +Our 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 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](https://app.sparkpost.com/templates) and also using the [templates API endpoint](https://developers.sparkpost.com/api/templates.html). + +As well as the usual HTML content, [SparkPost templates](https://www.sparkpost.com/docs/getting-started/creating-template/) can have optional plain-text and [AMP HTML](https://www.sparkpost.com/docs/user-guide/amp-for-email/) parts. The substitution variables work on these parts too. + +SparkPost has template [snippets](https://www.sparkpost.com/blog/get-started-snippets-sparkpost-email-templates/). Snippets are modular, reusable content that, once created, can be imported into the HTML, Text, or AMP part of any email template using a `render_snippet` macro call. + +SparkPost also supports [A/B testing](https://www.sparkpost.com/docs/tech-resources/a-b-testing-sparkpost/), a common method of comparing templates to see which one performs better. SparkPost provides the means to create automated A/B tests and view completed results. + +Tracking Your Email Activity +---------------------------- + +SparkPost offers two levels of tracking information. The Analytics Report is a richer and more complete form of Mailgun stats -- rolled up, time windowed summaries of your mailing and recipient activity. over 40 metrics are [viewable as customizable time series graphs](https://app.sparkpost.com/signals/analytics) and also available programmatically using our [metrics API endpoint](https://developers.sparkpost.com/api/metrics.html). + +The second level of tracking information exposes fine-grained individual activity. This individual activity is also available three ways -- through our [Events Search](https://www.sparkpost.com/docs/reporting/message-events/) interface,  by making use of the [events API endpoint](https://developers.sparkpost.com/api/events/), or by creating a [webhook](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) which pushes event data to your own systems. + +### Analytics Report + +Your SparkPost account includes an [extensive set of aggregate metrics](https://developers.sparkpost.com/api/metrics.html) for tracking your email activity. You can review [summary reports](https://app.sparkpost.com/signals/analytics), including a breakdown of bounces and engagement (our term for opens and clicks), and more. All of these reports can be narrowed by time window. 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 links above for a complete list of querying, filtering and comparison capabilities. + +All SparkPost aggregate metrics are stored on your account for 6 months. + +#### Message Events and Webhooks + +SparkPost's events API endpoint provides similar functionality (and then some!) to Mailgun's logs/events capability: [Events Search](https://www.sparkpost.com/docs/reporting/message-events/) provides a view of the last 10 days of events on your account. Those events are available in pull fashion by querying the [events API endpoint](https://developers.sparkpost.com/api/events/) directly and in push fashion if you use [webhooks](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/). + +SparkPost retains events for ten days; Mailgun starter accounts retain events for five days. + +Mailgun supports a single webhook per domain and event type. On SparkPost, you may create multiple webhooks, each filtered to receive one or more types of events. You can also create webhooks to [push the events relating to individual subaccounts](https://www.sparkpost.com/docs/user-guide/subaccounts/#summary-of-subaccount-features). + +Here's a mapping of each Mailgun event to its SparkPost message event equivalent(s): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mailgun eventSparkPost event
acceptedinjection
rejectedpolicy_rejection, generation_rejection
delivereddelivery
failedbounce, out_of_band
openedopen, initial_open, amp_open, amp_initial_open
clickedclick, amp_click
unsubscribedlist_unsubscribe, link_unsubscribe
complainedspam_complaint
stored–
+ +SparkPost has a single format for all event types, whereas Mailgun has "Webhooks" and "Legacy Webhooks" formats. + +SparkPost engagement tracking (opens and clicks) is enabled by default, and can be controlled for templates, individual messages (and specific links in a message) using [API options](https://developers.sparkpost.com/api/transmissions/#header-request-body). Mailgun open and click tracking is disabled by default, and is controlled through per-domain options in your account setup. + +#### Events documentation + +The SparkPost API includes embedded documentation, in the form of JSON specifications for the [events API](https://developers.sparkpost.com/api/events/#events-documentation) and [webhooks](https://developers.sparkpost.com/api/webhooks/#webhooks-documentation). + +### Metadata + +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](https://developers.sparkpost.com/api/transmissions.html#header-transmission-attributes) and for [each individual recipient](https://developers.sparkpost.com/api/recipient-lists.html#header-recipient-attributes), 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*](https://developers.sparkpost.com/api/inbound-domains.html)* before you can receive inbound mail through a relay webhook.* + +Subaccounts +----------- + +On SparkPost [plans](https://www.sparkpost.com/docs/faq/difference-between-starter-and-premier/) above "starter" level, you can create [subaccounts](https://www.sparkpost.com/docs/user-guide/subaccounts/) to support separate business units, mail streams or individual customers. Each subaccount has its own suppression list, and can have its own API keys, sending domains, templates etc. You can run reports / analytics by subaccount, get raw message event data by subaccount, get aggregated statistics, create webhooks per subaccount and so on. + +In addition you can enable your subaccount users to have permission to inject messages for delivery via their individual subaccount, and to use [the API](https://developers.sparkpost.com/api/subaccounts/) to access subaccount-specific resources. + +User Roles +---------- + +Mailgun and SparkPost both enable you to create users with specific roles. The SparkPost roles are: Admin, Developer, Templates, and Reporting, described [here](https://support.sparkpost.com/docs/user-guide/managing-users). + +Alerts +------ + +Your Mailgun account alerts you by email when approaching your account sending limit. In SparkPost, you can [set up alerts](https://www.sparkpost.com/docs/user-guide/alerts/) to track the following metrics: + +- Block Bounce Rate +- Hard Bounce Rate +- Soft Bounce Rate +- Monthly Sending Limit +- Health Score + +Alerts can send notifications via email, Slack, and webhooks. + +Dedicated IPs, IP Pools, and auto-warmup +---------------------------------------- + +SparkPost enables you to deliver email via IP addresses dedicated to your account (or subaccount). Similar to Mailgun, addresses are managed via [IP Pools](https://www.sparkpost.com/docs/deliverability/managing-dedicated-ip-pools/). Addresses can be set to [automatically warm up](https://support.sparkpost.com/docs/user-guide/automated-ip-warmup) over time, which is helpful in building a clean sender reputation as you migrate messages across. + +Health Score and other SparkPost Analytics features +--------------------------------------------------- + +These advanced analytics features are available in your SparkPost account, and don't have a direct equivalent in the Mailgun dashboard. + +- [Health Score](https://www.sparkpost.com/docs/reporting/health-score/) +- [Spam Trap Monitoring](https://www.sparkpost.com/docs/reporting/spam-trap-monitoring/) +- [Engagement Recency](https://www.sparkpost.com/docs/reporting/engagement-recency/) + +Mailgun paid accounts provide "inbox placement" monitoring that you can schedule at additional cost, using seed tests. + +What next? +---------- + +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](http://slack.sparkpost.com/)! If you have an issue with your SparkPost account, you can [check out our support articles here](https://www.sparkpost.com/docs/) and [contact our Support team directly from your app dashboard](https://app.sparkpost.com/dashboard). \ No newline at end of file diff --git a/content/docs/user-guide/mailjet-migration-guide.md b/content/docs/user-guide/mailjet-migration-guide.md new file mode 100644 index 000000000..bf038046f --- /dev/null +++ b/content/docs/user-guide/mailjet-migration-guide.md @@ -0,0 +1,181 @@ +--- +lastUpdated: "02/08/2020" +title: "Mailjet Migration Guide" +description: "Moving to SparkPost for better inbox delivery and higher performance? This Mailjet Migration Guide will help you start fast, spend less and deliver more." +--- + +Mailjet Migration Guide Overview +-------------------------------- + +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. + +Terminology +----------- + +Here is a quick table with the similar terms between the two services: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SparkPost termMailjet term
TransmissionMessage
RecipientsContacts/Recipients
MetricsStatistics
Message eventsEvents
MetadataEventPayload, Contact Metadata
TagsCustom ID
Sending domainSender address
Suppression listExclusion list
SubaccountSub-account
Relay webhookParse webhook
X-MSYS-API headerX-MAILJET-*, X-MJ-* headers
+ +Where To Get Help +----------------- + +If you're ready for the gritty details, check out our [DevHub](https://developers.sparkpost.com/), [API docs](https://developers.sparkpost.com/api) and [pricing](https://www.sparkpost.com/pricing/). If you have general questions, take a walk through our [support articles](https://support.sparkpost.com/), or if you just want to chat, [join our community on Slack](http://slack.sparkpost.com/). You can also [open a ticket](https://www.sparkpost.com/submit-a-ticket/) with our support team. + +Signing Up +---------- + +Sign up for your [SparkPost](https://app.sparkpost.com/join) or [SparkPost EU](https://app.eu.sparkpost.com/join) 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. + +Sending Your First Email +------------------------ + +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](https://www.sparkpost.com/migration-guides/mailjet/#migrating-to-the-rest-api) below. You can also send via [SMTP](https://www.sparkpost.com/migration-guides/mailjet/#sending-mail-over-smtp) if you prefer. + +Setting Up A Sending Domain +--------------------------- + +*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](https://app.sparkpost.com/account/sending-domains) ([EU](https://app.eu.sparkpost.com/account/sending-domains)) 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.* + +Important: Migrate Your Suppression List +---------------------------------------- + +*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](https://app.sparkpost.com/lists/suppressions/create) ([EU](https://app.eu.sparkpost.com/lists/suppressions/create)) or [via the API](https://developers.sparkpost.com/api/suppression-list.html#suppression-list-bulk-insert-update). + +Migrating to the SparkPost REST API +----------------------------------- + +*Terminology: MJ: Message -- SP: Transmission\ +**Terminology: MJ:  Contacts/Recipients -- SP: Recipients* + +The SparkPost [transmissions endpoint](https://developers.sparkpost.com/api/transmissions.html) 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](https://www.getpostman.com/), [cURL](https://curl.haxx.se/), or [HTTPie](https://httpie.org/), it's more common to use one of our official client or community libraries: + +- [php-sparkpost](https://github.com/SparkPost/php-sparkpost) +- [python-sparkpost](https://github.com/SparkPost/python-sparkpost) +- [node-sparkpost](https://github.com/SparkPost/node-sparkpost) +- [java-sparkpost](https://github.com/SparkPost/java-sparkpost) +- [go-sparkpost](https://github.com/SparkPost/gosparkpost) +- [elixir-sparkpost](https://github.com/SparkPost/elixir-sparkpost) +- [C#](https://github.com/darrencauthon/csharp-sparkpost) +- [Ruby](https://github.com/search?l=Ruby&q=sparkpost&type=Repositories&utf8=%E2%9C%93) + +Regardless of the tool you use, you need a [API key](https://app.sparkpost.com/account/api-keys) ([EU](https://app.eu.sparkpost.com/account/api-keys)) 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. + +Sending Mail Over SMTP +---------------------- + +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](https://developers.sparkpost.com/api/smtp-api.html) 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](https://developers.sparkpost.com/api/transmissions.html)*, *[*template*](https://developers.sparkpost.com/api/templates.html)* and *[*substitution*](https://developers.sparkpost.com/api/substitutions-reference.html)* capabilities.* + +Templates +--------- + +[SparkPost templates](https://developers.sparkpost.com/api/substitutions-reference.html) 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](https://app.sparkpost.com/templates) ([EU](https://app.eu.sparkpost.com/templates)) or using the [templates API endpoint](https://developers.sparkpost.com/api/templates.html). + +Tracking Your Email Activity +---------------------------- + +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](https://app.sparkpost.com/reports/summary) ([EU](https://app.eu.sparkpost.com/reports/summary)) and also are available programmatically using the [metrics API](https://developers.sparkpost.com/api/metrics.html) 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](https://app.sparkpost.com/reports/message-events) ([EU](https://app.eu.sparkpost.com/reports/message-events)) page, or through the [message events API](https://developers.sparkpost.com/api/message-events.html) endpoint and [webhooks](https://developers.sparkpost.com/api/webhooks.html) which let you process the data however you like. + +#### Metrics + +Your SparkPost account includes an [extensive set of metrics](https://developers.sparkpost.com/api/metrics.html) for tracking your email activity. You can review [summary reports](https://app.sparkpost.com/reports/summary) ([EU](https://app.eu.sparkpost.com/reports/summary)), a [breakdown of bounces](https://app.sparkpost.com/reports/bounces) ([EU](https://app.eu.sparkpost.com/reports/bounces)) and [engagement](https://app.sparkpost.com/reports/engagement) ([EU](https://app.sparkpost.com/reports/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. + +SparkPost stores all your metrics for 6 months. + +#### Message Events and Webhooks + +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](https://developers.sparkpost.com/api/message-events.html#message-events-message-events-get) and in push fashion if you use [the webhooks feature](https://developers.sparkpost.com/api/webhooks.html), 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. + +### Sidebar: Events Specifications + +The SparkPost API includes embedded JSON specifications and sample event generation services for both [message events](https://developers.sparkpost.com/api/message-events.html#message-events-events-samples) and [webhooks](https://developers.sparkpost.com/api/webhooks.html#webhooks-events-samples-get). + +Inbound Email +------------- + +*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*](https://developers.sparkpost.com/api/inbound-domains.html)* before you can receive inbound mail through a relay webhook.* \ No newline at end of file diff --git a/content/docs/user-guide/mandrill-migration-guide.md b/content/docs/user-guide/mandrill-migration-guide.md index 081c127ef..4ed6fa463 100644 --- a/content/docs/user-guide/mandrill-migration-guide.md +++ b/content/docs/user-guide/mandrill-migration-guide.md @@ -1,7 +1,226 @@ --- lastUpdated: "02/08/2020" title: "Mandrill Migration Guide" -description: "In the wake of the changes at Mandrill Spark Post has offered to take on any departing Mandrill users and to honor Mandrill’s pricing for those users As a company Spark Post would like to make the transition as seamless as possible Please view our Migration guide We also have..." +description: "This Mandrill Migration Guide explains how quick and painless migrating to SparkPost from Mandrill can be, reducing the impact to the developer community." --- -In the wake of the changes at Mandrill, SparkPost has offered to take on any departing Mandrill users and to honor Mandrill’s pricing for those users. As a company, SparkPost would like to make the transition as seamless as possible. Please view our [Migration guide](https://www.sparkpost.com/mandrill-migration-guide). We also have [a blog post](https://www.sparkpost.com/blog/mandrill-alternative-sparkpost-survival-guide/) that provides more detail. +Mandrill Migration Guide Overview +--------------------------------- + +Mailchimp recommends SparkPost as a Mandrill alternative for developers looking for a transactional email provider. To support your move, we've created this Mandrill migration guide to streamline the process. We also recommend reading through our full [getting started guide](https://www.sparkpost.com/docs/getting-started/getting-started-sparkpost/) for an overview of SparkPost. + +Terminology +----------- + +We'll start with a comparison of terms: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SparkPost termMandrill term
TransmissionsMessages
RecipientsRecipients
TemplatesTemplates
MetricsTime Series Reports
Message EventsMessage Information
WebhooksWebhooks
MetadataMetadata
Substitution dataMerge vars
TagsTags
Sending DomainSending Domain
Bounce DomainReturn Path Address
SubaccountSubaccount
Suppression ListRejection Blacklist
Inbound Domain/Relay WebhookInbound Domain/Inbound Route
X-MSYS-API headerX-MC-* headers
+ +### API Differences + +- All calls to the Mandrill API are made with HTTP POST. Calls to SparkPost use the different HTTP methods: GET, POST, PUT, DELETE. +- The SparkPost API accepts and returns only JSON. + +SparkPost API calls are authenticated by passing a valid API key through the [HTTP Authorization Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) + +Where To Get Help +----------------- + +If you're in a hurry, don't have time to read this Mandrill Migration Guide and just want the gritty details, check out our [Developer Site](https://developers.sparkpost.com/), [API reference](https://developers.sparkpost.com/api/) and [pricing](https://www.sparkpost.com/pricing/). If you have general questions, [take a look through our support articles](https://support.sparkpost.com/) or if you just want to chat, [join our community on Slack](http://slack.sparkpost.com/). + +Signing Up +---------- + +Sign up for your [SparkPost](https://app.sparkpost.com/join) or [SparkPost EU](https://app.eu.sparkpost.com/join) account. An account created with SparkPost cannot be used with SparkPost EU, and vice-versa. Customers may use accounts in both regions. + +If you evaluated SparkPost when Mandrill was converted to a Mailchimp add-on, you may have an existing SparkPost account which could contain your sending domains. + +#### SparkPost EU + +SparkPost is available in multiple regions. "SparkPost" refers to the SparkPost service hosted in North America. "SparkPost EU" refers to the SparkPost service hosted in Western Europe. An account created with SparkPost cannot be used with SparkPost EU, and vice-versa. Customers may use accounts in both regions. + +Setting Up Domains +------------------ + +*Terminology: MD: sending domain -- 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](https://app.sparkpost.com/account/sending-domains) ([EU](https://app.eu.sparkpost.com/account/sending-domains)) page. We recommend using a subdomain with SparkPost, like "mail.yourdomain.com". You will need to verify your domain by publishing DNS records. [Create a sending domain](https://app.sparkpost.com/account/sending-domains/create) ([EU](https://app.eu.sparkpost.com/account/sending-domains/create)) from your account to see the specific record values. Be sure to delete any Mandrill related records on the domain. SparkPost uses CNAME records for custom Return Paths, so SPF records are not necessary. Once you add a sending domain with SparkPost, you can send from any localpart just like with Mandrill. + +Important: Migrate Your Suppression List +---------------------------------------- + +*Terminology: MD: Blacklist/Whitelist -- SP: Suppression list* + +SparkPost's Suppression List operates similar to the Rejection BlackList on Mandrill. As you send, it collects recipients that have unsubscribed, submitted a spam complaint, or hard bounced. It's important that you transfer your Mandrill Rejection Blacklist to your SparkPost Suppression List, in order to protect your sending reputation. + +To move your blacklist, do the following: + +1. [Export your Rejection Blacklist](https://mandrill.zendesk.com/hc/en-us/articles/205582997-How-do-I-export-my-Rejection-Blacklist-) from Mandrill to get started. +2. You can either upload a CSV to your account or use the API: + - [Upload a CSV to your account](https://app.sparkpost.com/lists/suppressions/create) ([EU](https://app.eu.sparkpost.com/lists/suppressions/create)). The format is: + + recipient,type,description + dont@send.com,non_transactional,"Mandrill BlackList" + spam@complaint.com,non_transaction,"Spam Complaint" + not@exist.com,transactional, + not@exist.com,non_transactional, + + The top heading row is required. Types can be either `transactional` or `non_transactinal`, depending on which type of emails should be suppressed. The description is an optional note on why the recipient is suppressed, in quotes. + +- [Suppression List API Bulk Insert](https://developers.sparkpost.com/api/suppression-list/#suppression-list-put-bulk-create-or-update-suppressions) + +Migrating to the SparkPost REST API +----------------------------------- + +*Terminology: MD: Message -- SP: Transmission*\ +*Terminology: MD: Recipients -- SP: Recipients* + +After getting your account set up, the best place to get started with the SparkPost API is the [API Reference](https://developers.sparkpost.com/api/). Almost every feature available to your SparkPost account is accessible via the API. The most commonly used part of the API is the [Transmissions API endpoint](https://developers.sparkpost.com/api/transmissions.html), which is broadly equivalent to Mandrill's Messages API. Unlike Mandrill, SparkPost has a single endpoint for sending inline content, templates, and raw email bodies, making it easier by having a single entry point for integrating with our API. A SparkPost transmission is a mailing to one or more recipients, with substitution data for personalization, metadata for tracking, and stored templates. + +While you can directly call the API via tools like [Postman](https://www.getpostman.com/), [cURL](https://curl.haxx.se/), or [HTTPie](https://httpie.org/), it's more common to use one of our official client or community libraries: + +- [php-sparkpost](https://github.com/SparkPost/php-sparkpost) +- [python-sparkpost](https://github.com/SparkPost/python-sparkpost) +- [node-sparkpost](https://github.com/SparkPost/node-sparkpost) +- [java-sparkpost](https://github.com/SparkPost/java-sparkpost) +- [go-sparkpost](https://github.com/SparkPost/gosparkpost) +- [elixir-sparkpost](https://github.com/SparkPost/elixir-sparkpost) +- [C#](https://github.com/darrencauthon/csharp-sparkpost) +- [Ruby](https://github.com/search?l=Ruby&q=sparkpost&type=Repositories&utf8=%E2%9C%93) + +Regardless of the tool you use, you need a [API key](https://app.sparkpost.com/account/api-keys) ([EU](https://app.eu.sparkpost.com/account/api-keys)) to use the SparkPost API. 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. + +Sending Mail Over SMTP +---------------------- + +SparkPost accepts email over traditional SMTP. To authenticate, set the SMTP user  to `SMTP_Injection` and the SMTP password to a SparkPost API key with "Send via SMTP" permissions. A full list of SMTP settings can be found on the [SMTP Reference](https://developers.sparkpost.com/api/smtp/). + +#### SMTP Headers + +Mandrill allows you to set  a variety of headers (X-MC-*) on SMTP requests to customize your emails. SparkPost offers similar access to metadata, tracking options, and more under one SMTP header: X-MSYS-API. For more informations, see the [SMTP Reference](https://developers.sparkpost.com/api/smtp/#header-using-the-x-msys-api-custom-header). To use more advanced features like dynamic content and Templates, you should use the [REST API](https://www.sparkpost.com/migration-guides/mandrill/#migriating-to-the-rest-api). + +Templates +--------- + +When it comes to storing reusable pieces of email content, the Templates feature in Mandrill and SparkPost are very similar. They both support HTML and text content, have publish and draft mechanics, and can be managed either from the [editor on your account](https://app.sparkpost.com/templates) or via the [API](https://developers.sparkpost.com/api/templates). The important difference is how dynamic content is handled. Mandrill supports using either the MailChimp template language or Handlebars. SparkPost Templates and Transmissions support the [SparkPost Template Language](https://developers.sparkpost.com/api/template-language/), which uses a Handlebars-like syntax. If you have many Mandrill-Handlebars templates, we recommend checking out our [Template Migration tool](https://www.sparkpost.com/blog/mandrill-template-migration-tool-mst3k/). + +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](https://app.sparkpost.com/templates) ([EU](https://app.eu.sparkpost.com/templates)) or using the [templates API endpoint](https://developers.sparkpost.com/api/templates.html). + +Tracking Your Email Activity +---------------------------- + +SparkPost offers 2 levels of tracking information. The first is aggregate metrics which are rolled up, time windowed summaries of your activity. These are [viewable as customizable time series graphs](https://app.sparkpost.com/reports/summary) and also available using the [Metrics API endpoint](https://developers.sparkpost.com/api/metrics.html). 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 page](https://app.sparkpost.com/reports/message-events) or [API endpoint](https://developers.sparkpost.com/api/message-events). The [Webhooks](https://app.sparkpost.com/account/webhooks) feature delivers events to an HTTP endpoint of your choice as they are generated. + +#### Metrics + +*Terminology: MD: Time Series Reports -- SP: Metrics* + +Your SparkPost account includes an extensive set of metrics for tracking your email activity, stored for 6 months. You can review [summary reports](https://app.sparkpost.com/reports/summary), a [breakdown of bounces](https://app.sparkpost.com/reports/bounces) and [engagement](https://app.sparkpost.com/reports/engagement) (our term for opens and clicks), and more. All of these reports can be narrowed by time window, down to the minute, by campaign ID, which you can set on each transmission, and by other fields such as recipient domain and IP pool. See the [Metrics API Reference](https://developers.sparkpost.com/api/metrics.html) for a complete list of querying and filtering capabilities. + +#### Message Events and Webhooks + +*Terminology: MD: Message Information -- SP: Message Events* + +Message Events are all the individual events that happen around the emails you send. The [Message Events page](https://app.sparkpost.com/reports/message-events) is a searchable view of the last 1000 events. Events are also available by querying the [Message Events API endpoint](https://developers.sparkpost.com/api/message-events.html#message-events-message-events-get). Message Events data is stored for 10 days. The events are also available in a push fashion through [Webhooks](https://app.sparkpost.com/webhooks). For app integration, we recommend webhooks since they offer resilient, low latency, near-real-time access to events as they happen. + +#### Metadata + +*Terminology: MD: metadata -- SP: metadata*\ +*Terminology: MD: tags -- SP: tags* + +SparkPost offers metadata and tags as mechanisms for labeling your email activity with information from your application. You can provide metadata with your transmissions, both at the top level and for each individual recipient, with recipient metadata overriding top-level values. Any metadata you provide at message send time will later be available in all events relating to that message. Metadata can also be set using the X-MSYS-API message header when sending with SMTP. + +Migrating your Traffic +---------------------- + +*For high volume and non-transactional senders, please take note of this section.* + +We recommend signing up for a SparkPost account and segmenting your traffic between SparkPost and Mandrill, to build your reputation with our service and warm up your dedicated IPs properly. Be sure to follow our best practices guides for [warming up your IPs](https://www.sparkpost.com/docs/deliverability/ip-warm-up-overview/) and [optimizing deliverability and get the best inbox placement rates](https://www.sparkpost.com/docs/deliverability/optimizing-deliverability-and-inbox-placement/). + +Subaccounts +----------- + +If you send on behalf of your customers, it's a good idea to use [SparkPost's subaccounts](https://www.sparkpost.com/docs/user-guide/subaccounts/) to segment their data. Similar to Mandrill, you are able to see analytics for each subaccount in your [reports](https://app.sparkpost.com/reports/summary). SparkPost also allows you to assign most account assets, like Sending Domains or Templates, to an individual subaccount. Once assigned, only that subaccount and the master account can access the resource. + +Inbound Email +------------- + +*Terminology: MD: Inbound Route -- SP: Relay Webhook* + +Similar to the inbound domains and inbound routes in Mandrill, SparkPost's inbound domains and relay webhooks process and forward email addressed to an HTTP endpoint you control. You will have to set new MX records for SparkPost to receive mail on your behalf. See the [API reference](https://developers.sparkpost.com/api/inbound-domains/) for more information. + +Each relay webhook accepts SMTP traffic on your behalf, and forwards JSON-encoded messages to you over HTTP. Unlike Mandrill, SparkPost only allows for one webhook per domain, and forwards all mail sent to the domain over to your endpoint. \ No newline at end of file diff --git a/content/docs/user-guide/media/mailgun-migration-guide/migration-guide-sparkpost-dashboard.png b/content/docs/user-guide/media/mailgun-migration-guide/migration-guide-sparkpost-dashboard.png new file mode 100644 index 000000000..1a9a3e4f5 Binary files /dev/null and b/content/docs/user-guide/media/mailgun-migration-guide/migration-guide-sparkpost-dashboard.png differ diff --git a/content/docs/user-guide/media/migrating-from-sendgrid/Sendgrid-Migration-guide_600x300-01.png b/content/docs/user-guide/media/migrating-from-sendgrid/Sendgrid-Migration-guide_600x300-01.png new file mode 100644 index 000000000..7ae43e4dd Binary files /dev/null and b/content/docs/user-guide/media/migrating-from-sendgrid/Sendgrid-Migration-guide_600x300-01.png differ diff --git a/content/docs/user-guide/media/migrating-from-sendgrid/sparkpost-dashboard.png b/content/docs/user-guide/media/migrating-from-sendgrid/sparkpost-dashboard.png new file mode 100644 index 000000000..d6dc38700 Binary files /dev/null and b/content/docs/user-guide/media/migrating-from-sendgrid/sparkpost-dashboard.png differ diff --git a/content/docs/user-guide/migrating-from-sendgrid.md b/content/docs/user-guide/migrating-from-sendgrid.md index 0f3ce0145..15937718a 100644 --- a/content/docs/user-guide/migrating-from-sendgrid.md +++ b/content/docs/user-guide/migrating-from-sendgrid.md @@ -1,11 +1,206 @@ --- lastUpdated: "08/25/2020" title: "Migrating From SendGrid" -description: "Changing email providers can be a time consuming process, but if you're coming from SendGrid, we've got you covered. Many differences between SendGrid and SparkPost can be attributed to terminology and approach, both of which you can get help with by referring to our..." +description: "Moving to SparkPost for better inbox delivery and higher performance? This SendGrid Migration Guide will help you start fast, spend less and deliver more." --- -Changing email providers can be a time consuming process, but if you're coming from SendGrid, we've got you covered. Many differences between SendGrid and SparkPost can be attributed to terminology and approach, both of which you can get help with by referring to our [SendGrid Migration Guide.](https://messagebird.com/migration-guides/sendgrid) +SendGrid Migration Guide Overview +--------------------------------- -If you're in a hurry, though, and you don’t have time to read this SendGrid Migration Guide and just want the gritty details, check out our [DevHub](https://developers.sparkpost.com/?_ga=2.57180074.1255629289.1508772206-1202146721.1501712582), [API docs](https://developers.sparkpost.com/api/?_ga=2.57180074.1255629289.1508772206-1202146721.1501712582), or [pricing](https://www.sparkpost.com/pricing/). If you have general questions, take a look through our [support articles](https://www.sparkpost.com/docs/), or if you just want to chat, [join our community on Slack](https://slack.sparkpost.com/?_ga=2.22115515.1255629289.1508772206-1202146721.1501712582). +This SendGrid Migration Guide is here to help make your move from SendGrid to SparkPost as smooth as possible. We'll walk through the key setup steps and highlight the differences in technology and terminology along the way. -Thanks for choosing SparkPost! +![sendgrid migration guide image](media/migrating-from-sendgrid/Sendgrid-Migration-guide_600x300-01.png) + +Terminology +----------- + +First here's a quick primer on the main terminology differences between the two services. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SparkPost termSendGrid term
Transmissionmail
Recipientspersonalizations
Metricsstats
Message eventsbounces, invalid emails, block, spam reports
Metadatacustom args
Tagscategories
Sending domaindomain whitelabel
Subaccountsubuser
Relay webhookInbound parse webhook
X-MSYS-API headerX-SMTPAPI header
+ +Where To Get Help +----------------- + +If you're in a hurry, don't have time to read this SendGrid Migration Guide and just want the gritty details, check out our [DevHub](https://developers.sparkpost.com/), [API docs](https://developers.sparkpost.com/api/) and [pricing](https://www.sparkpost.com/pricing/). If you have general questions, [take a look through our support articles](https://support.sparkpost.com/) or if you just want to chat, [join our community on Slack](http://slack.sparkpost.com/). + +Signing Up +---------- + +Sign up for your SparkPost account [here](https://app.sparkpost.com/sign-up). The first visible difference here is that all API features are available on all plans. That means you can purchase dedicated IPs and use subaccounts (our name for subusers) straight off the bat. Then you can select [add-ons](https://www.sparkpost.com/pricing/) to meet your needs. + +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. + +#### Sidebar: The SparkPost Dashboard + +After sign-up and whenever you [sign in](https://app.sparkpost.com/dashboard), 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](media/migrating-from-sendgrid/sparkpost-dashboard.png) + +Sending Your First Email +------------------------ + +At this point, you can send email provided you use the *sparkpostbox.com* domain in your 'From' address (e.g. "From: something@sparkpostbox.com"). 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. To begin sending real production emails, SparkPost assumes you will use a domain of your own. This is a little different than SendGrid which lets you send email from your own domain but 'via' a shared SendGrid domain. + +If you would like to jump straight in and send your first email, check out the [REST API section](https://www.sparkpost.com/migration-guides/sendgrid/#migrating-to-the-rest-api) below.  You can also send via [SMTP](https://www.sparkpost.com/migration-guides/sendgrid/#sending-mail-over-smtp) if you prefer. + +Setting Up A Sending Domain +--------------------------- + +*Terminology: SG: whitelabeled domain -- SP: sending domain* + +To begin sending mail from your own domain, you must configure a sending domain within your account so SparkPost can verify that you own it. You can create and manage your sending domains from [Sending Domains](https://app.sparkpost.com/account/sending-domains) in the Accounts menu. + +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 both SPF and DKIM on your domains, as it will improve your domain's reputation, and thus, your chances of consistently hitting the inbox.* + +### Sidebar: Service Providers + +*Terminology: SG: subuser -- SP: subaccount* + +Are you sending mail on behalf of many customers from lots of different domains? SparkPost has a subaccounts feature for just this situation. SparkPost's REST API is the way to go for onboarding your customers and configuring their sending domains. You can [create a subaccount](https://developers.sparkpost.com/api/subaccounts.html#subaccounts-subaccounts-collection-post) and [sending domain](https://developers.sparkpost.com/api/sending-domains.html#sending-domains-create) programmatically for each customer. Each subaccount gets an API key and each sending domain a DKIM key. 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. + +Happily, you can use the [SparkPost CLI](https://github.com/SparkPost/sparkpost-cli) to migrate your SendGrid suppression list into SparkPost. + +Migrating to the SparkPost REST API +----------------------------------- + +*Terminology: SG: mail -- SP: transmission* + +*Terminology: SG: personalizations -- SP: recipients* + +The most commonly used part of the SparkPost API is the [transmissions API endpoint](https://developers.sparkpost.com/api/transmissions.html), which is broadly equivalent to SendGrid's v3 mail API. A SparkPost transmission is a mailing to one or more recipients, with substitution data for personalization, metadata for tracking, and templates that can be stored ahead of time or specified inline with your transmission. Be sure to include the campaign ID with your transmissions. You can filter SparkPost reports by campaign ID after the fact when you want to review mailing performance. + +The rest of the API lets you track mail at the event level, extract aggregate metrics, and manage your account. Check out the [SparkPost API reference documentation](https://developers.sparkpost.com/api/) for details. + +You can call the SparkPost API directly using tools like [cURL](https://curl.haxx.se/) or [HTTPie](https://httpie.org/) but it's more common to use one of our official client libraries: + +- [php-sparkpost](http://github.com/SparkPost/php-sparkpost) +- [python-sparkpost](http://github.com/SparkPost/python-sparkpost) +- [node-sparkpost](http://github.com/SparkPost/node-sparkpost) +- [java-sparkpost](http://github.com/SparkPost/java-sparkpost) +- [go-sparkpost](https://github.com/SparkPost/gosparkpost) +- [elixir-sparkpost](https://github.com/SparkPost/elixir-sparkpost) + +Our thriving developer community also maintains libraries for other languages and platforms including [C#](https://github.com/darrencauthon/csharp-sparkpost) and [Ruby](https://github.com/search?l=Ruby&q=sparkpost&type=Repositories&utf8=%E2%9C%93). + +Whichever tools you choose, you will need to [issue yourself an API key](https://app.sparkpost.com/account/credentials) to start using the SparkPost API. 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 +---------------------- + +*Terminology: SG: X-SMTPAPI -- SP: X-MSYS-API* + +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. You can read the full [SparkPost SMTP API reference documentation here](https://developers.sparkpost.com/api/smtp-api.html). + +*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*](http://developers.sparkpost.com/api/transmissions.html)*, *[*template*](https://developers.sparkpost.com/api/templates.html)* and *[*substitution*](https://developers.sparkpost.com/api/substitutions-reference.html)* capabilities.* + +Templates +--------- + +[SparkPost templates](https://developers.sparkpost.com/api/substitutions-reference.html) are conceptually simpler than SendGrid's transactional templates but with a more powerful featureset including [conditional logic](https://developers.sparkpost.com/api/substitutions-reference.html#header-if-then-else-syntax), [iteration](https://developers.sparkpost.com/api/substitutions-reference.html#header-array-iteration), and [fine grained link tracking controls](https://developers.sparkpost.com/api/substitutions-reference.html#header-personalized-links). You can also use rich substitution data with SparkPost templates including arrays and nested objects allowing personalization options and simpler integration with your own applications. + +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}}* + +You can create, edit and preview your templates (using test substitution data) [within SparkPost](https://app.sparkpost.com/templates) and also using the [templates API endpoint](https://developers.sparkpost.com/api/templates.html). + +*Note: where SendGrid versions templates, SparkPost has a draft and a published version of each template, allowing you to edit and send at the same time.* + +Tracking Your Email Activity +---------------------------- + +SparkPost offers 2 levels of tracking information. The first is aggregate metrics which are broadly equivalent to SendGrid stats -- rolled up, time windowed summaries of your activity. These are [viewable as customizable time series graphs](https://app.sparkpost.com/reports/summary) and also available programmatically using our [metrics API endpoint](https://developers.sparkpost.com/api/metrics.html). 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](https://app.sparkpost.com/reports/message-events) interface, or by making use of our message events API endpoint and [webhooks](https://app.sparkpost.com/account/webhooks) features which let you process the data however you like. + +#### Metrics + +*Terminology: SG: stats -> SP: metrics* + +Your SparkPost account includes an [extensive set of metrics](https://developers.sparkpost.com/api/metrics.html) for tracking your email activity. You can review [summary reports](https://app.sparkpost.com/reports/summary), a [breakdown of bounces](https://app.sparkpost.com/reports/bounces) and [engagement](https://app.sparkpost.com/reports/engagement) (our term for opens and clicks), and more.  All of these reports can be narrowed by time window, down to the minute, by campaign ID, which you can set on each transmission, 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. + +#### Message Events and Webhooks + +SparkPost's message events API endpoint provides similar functionality (and then some!) to SendGrid's bounce, invalid email, and spam report APIs: the [message events report](https://app.sparkpost.com/reports/message-events) is a searchable view of the last 10 days of events of all types. Those events are available in pull fashion by [querying the message events endpoint directly](https://developers.sparkpost.com/api/message-events.html#message-events-message-events-get) and in push fashion if you use [the webhooks facility](https://developers.sparkpost.com/api/webhooks.html). The SparkPost webhooks facility is, on the surface, similar to the SendGrid one but with far richer per-event detail including bounce classification details, geolocation info, delivery latency numbers and more. For app integration, we recommend webhooks since they offer resilient, low latency, near-real-time access to events as they happen. + +### Sidebar: Events Specifications + +The SparkPost API includes embedded JSON specifications and sample event generation services for both [message events](https://developers.sparkpost.com/api/message-events.html#message-events-events-samples) and [webhooks](https://developers.sparkpost.com/api/webhooks.html#webhooks-events-samples-get). + +#### Metadata + +*Terminology: SG: custom args -- SP: metadata* + +*Terminology: SG: categories -> SP: tags* + +SparkPost offers metadata and tags as mechanisms for labeling your email activity with information from your application, similar to SendGrid's custom args and categories features. + +You can provide metadata with your transmissions, both at the top level and for each individual recipient, with recipient metadata overriding top-level values. Any metadata you provide at message send time will later be available in all events relating to that message. + +*Note: metadata can also be set using the X-MSYS-API message header when sending with SMTP.* + +Inbound Email +------------- + +*Terminology: SG: inbound parse webhook -- SP: relay webhook* + +SparkPost's relay webhooks process and forward email addressed to a domain you control, very similar to SendGrid's "inbound parse" mechanism. 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*](https://developers.sparkpost.com/api/inbound-domains.html)* before you can receive inbound mail through a relay webhook.*