Getting Started with SparkPost

May 12, 2017 Contributors  all

Welcome to SparkPost! This guide describes the steps you’ll need to follow to start sending mail using our service. We’ll run through account setup and best practices to have in place before you begin sending. We’ll also point out some useful resources along the way to help you get the best from SparkPost.

Note: SparkPost is a developer-centric email delivery service. That means pretty much everything described in this guide can be done through the SparkPost API. If you’d like to just skip to the end, the SparkPost API documentation is worth a visit.

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

Signing Up And In

First things first: sign up for your free SparkPost account here (EU). After sign-up, SparkPost will send you a verification email; please do verify your email address so SparkPost can contact you if you need support later on and send you important service announcements.

Preparing Your "From:" Address

The very first thing your recipients see when they open your email is your address in the From field so it’s important to set it properly from the get-go. In SparkPost, that means creating a sending domain, the domain name you’ll use to send email from. You can either use a top-level domain such as myawesomedomain.com or, if you prefer, a subdomain like mail.myawesomedomain.com. You can register as many sending domains as you need on your SparkPost account.

Prerequisites

To create a sending domain in SparkPost, you will need ownership or administrative access to your domain name, for example: myawesomedomain.com. You will also need access to make DNS configuration changes through your domain registrar (or DNS provider) for your sending domain.

If you do not have a domain name, you’ll need to purchase one to use with SparkPost. Here are a few useful and popular domain name registrars:

To set up your sending domain, you add the domain to your SparkPost account, verify that you own it and wait a moment while our Compliance team runs a few quick checks. Follow the detailed steps below to get it done.

Note: SparkPost’s Compliance team expect to see a legitimate web presence on each sending domain so please ensure your website is accessible before adding a domain to your SparkPost account.

Sending Domain Step 1: Creating the Domain

If you didn’t create a sending domain during your sign up process, you can add one now in the SparkPost app (EU). If you already added a domain, visit the Sending Domains page (EU) to find your existing domain and click "View Settings" to complete the domain set up. In both cases, you should now be on your domain’s edit page and see that it has a status of "Unverified".

Sending Domain Step 2: Verifying Domain Ownership

Before you can send mail using your sending domain, SparkPost needs to verify that you own it. Adding a DNS record to your domain is the recommended way to complete this verification. The edit screen, under Set Up For Sending, shows a TXT record value along with a funny-looking hostname where SparkPost expects to find that TXT record. For example, the demo hostname shown below is scph0717._domainkey.mail.example.com and the value of the TXT record begins with "v=DKIM1;".

Once you’ve set up the DNS TXT record, come back to the edit screen and click "Verify TXT Record". Unfortunately, some DNS records take longer to update than others, so you may have to try this a few times or, in rare cases, come back up to 24 hours later and click "Verify TXT Record" again. If you want, you can check to see if the DNS value has updated using a service like Whats My DNS. Just be sure to use the correct hostname there, too.

Also, please note that some providers are particular about how the hostname is entered, so you may need to remove the domain from the end of the "Hostname" record and enter it as scphxxxx._domainkey (where xxxx is the number provided in the "Hostname" record in the SparkPost UI). If the record still does not verify, then please check with your domain provider if there are any special requirements for entering your DNS TXT record.

You’re almost done! While you’ve been verifying ownership of your domain, the addition of this DKIM DNS record will also help your reputation as an email sender. DKIM is a widely-used email standard that most email services will use to verify that your emails were in fact sent by you and weren’t intercepted or changed along the way. Your hard work is paying off already.

Note: if you don’t have access to update your DNS records for this domain, you can click "verify ownership through email" to ask SparkPost to send an email to [email protected], [email protected] or any mailbox that you control on your domain, and then click on the link in the received email. This will allow you to send email from this domain, but SparkPost will not be able to DKIM-sign the mail it sends on your behalf, which could cause deliverability issues. We recommend using DNS verification whenever possible for this reason.

Here are some how-to documents for editing DNS records with common DNS providers:

Sending Domain Step 3: Final Review

Once your DNS record has been found, your domain’s status will change to "Pending". This means the domain has been picked up by our final review process which will verify that the domain meets our best practice requirements. This usually takes just a few minutes, but can sometimes take up to an hour. Once the review is complete, the domain’s status will change to "Verified" and "Ready for: Sending" (and DKIM-signing if you set up your DKIM DNS record).

Important: Coming From Other Email Services

Now that you have an account and a domain, it’s tempting to just start sending mail. If you’re coming from another email service though, there is just 1 more vitally important step required to ensure you only send mail to the right people.

Most services will build up a list of addresses to avoid emailing in a suppression or black list. This list contains all your collected typo addresses along with those which have unsubscribed over time and also those who have complained. Your SparkPost account has a suppression list but it’s empty to begin with and it really needs all those addresses from your old service.

It is extremely important you bring your suppression list into SparkPost to avoid sending mail to those addresses. Otherwise your account could be suspended and your reputation as an email sender will suffer.

You can upload a CSV suppression list to your account at Lists -> Suppressions (EU). The format is nice and simple:

  • Email address
  • Suppression type: "transactional" or "non_transactional" depending on which type of mail should be suppressed
  • Transactional emails one-time notifications such as password resets and purchase confirmations
  • Non-transactional emails include high-volume traffic such as newsletters and marketing communications
  • Description: notes on why this address is suppressed

Once your suppression list has been imported, you are ready to send safely and successfully.

Here are migration guides for other popular Email Services:

Sending Email

SparkPost is a developer-centric email delivery service. That means it comes with a comprehensive REST API for sending mail, tracking engagement and so on. If you’d like to dive right in, you can read the API reference documentation and we have a collection for Postman to help you experiment with manual API calls.

In case you need it, SparkPost also supports SMTP-based email delivery with a few modern twists.

Authentication

Whether you use the API or SMTP, SparkPost expects an API key along with each request you make, as an authentication token. You can issue and manage the API keys on your account from from Account -> API Keys (EU), each with its own permissions so you can restrict what each key is used for.

For REST API calls, your API key must be included in an Authorization header on your HTTP request:

For SMTP delivery, the API key is used as an SMTP authentication password. You can read more about that in the Sending With SMTP section below.

Sending With The REST API

The modern way to send email with SparkPost is using the REST API’s transmissions endpoint which supports high volume, multi-recipient delivery, personalized message templates, per-recipient metadata and a slew of other capabilities besides. Here’s a simple transmission request:

SparkPost API Client Libraries

SparkPost provides libraries, add-ons and plugins for various environments, to simplify your integration:

SparkPost also offers a Heroku add-on, a Zapier zap and a WordPress plugin.

Sending With SMTP

If you need to integrate with a service which only speaks SMTP, you can use these settings:

  • SMTP host: smtp.sparkpostmail.com
  • Port: 587 or 2525
  • Encryption: STARTTLS
  • Username: SMTP_Injection
  • Password: <api key with "send via SMTP" permission>

Note: some hosting providers block outbound SMTP so you may need to request that access before you can send via SMTP from your host.

You can also review these settings from Account -> SMTP Relay (EU). For more details including how to use advanced SMTP features, check out the SMTP API reference.

Tracking Recipient Behavior

SparkPost can automatically track when your recipients open your email and click on the links inside.

Either way, you can use the engagement tracking report in Reports -> Engagement (EU)to review a summary of recipient engagement with your emails. You can also search the message events report in Reports -> Message Events (EU) to see individual, per-email open and click events.

Tracking With The REST API

The SparkPost API has open and click tracking enabled by default. You can also control open and click tracking on each transmission by setting the options.open_tracking and options.click_tracking fields respectively.

Tracking With SMTP

To enable tracking on SMTP, you can add an X-MSYS-API header to your messages with the open_tracking and click_tracking fields set:

You can also control SMTP tracking at the account level in Account -> SMTP Relay (EU)).

Improving Reputation And Branding

To maintain your sending reputation and ensure the mail you send is branded as your recipients expect, you can create a custom bounce domain and custom tracking domain for your SparkPost account.

Custom Bounce Domain

Each email you send will have 2 main sender addresses:

  • The header from address is the one that appears in the From: field. The header from address includes one of your sending domains.
  • The bounce address appears in the Return-Path header and is used by mail software to return undeliverable mail and report on errors.

By default, SparkPost uses a generic bounce domain for your email, such as sparkpostmail.com. In SparkPost, you can create custom bounce domains to control the branding of your emails more fully as well as to create a deliverability best practice known as SPF alignment. Creating a related bounce domain creates "relaxed alignment", which is good (e.g. mail.example.com and bounces.example.com), while setting up an existing sending domain as a bounce domain creates "strict alignment", which is even better (e.g. mail.example.com used as both).

To do this, visit the Sending Domains page (EU) and either create a new domain or edit an existing sending domain. In either case, you will need to edit DNS records to set up your bounce domain (no other verification methods are available for bounce domain setup). Add the CNAME record with the value shown under Set Up For Bounce, click "Verify CNAME Record" (DNS updates can take up to 24 hours to complete, but are usually available within an hour), and the domain will show up as "Ready for: Bounce" (along with anything else it was already ready for).

Tracking Domain

If you have click-tracking turned on, SparkPost will wrap each link in your emails to add tracking information, replacing each URL with a tracking service URL using the generic SparkPost domain name: spgo.io. You can create your own custom tracking domains from Account -> Tracking Domains (EU) and also through the API and then assign them to be used with specific sending domains. You can assign a tracking domain to a sending domain in the SparkPost app under Sending Domains (EU).

Reports, Analytics and Tracking

You can use message events, metrics, and webhooks to keep track of your SparkPost account activity and email delivery performance. Metrics and message events are both available visually and through the SparkPost API, while webhooks offer an efficient way to have SparkPost push message events directly to your own app.

Summary report

Message Events

Message events offer fine grained, per-recipient details, useful for checking the status of a single message or recipient. When you ask SparkPost to send an email, it emits a sequence of events so you can see when it’s delivered, when the recipient opens it and clicks on links, and various related events. Here’s a diagrammatic view of SparkPost’s major message events in sequence:

SparkPost message events in sequence

You can search 10 days of message events from your account in Reports -> Message Events (EU) with the same data available through the message events API endpoint.

Webhooks

SparkPost also includes a webhooks facility to give your app the ability to store and act upon a live stream of message events. You can register your own HTTP endpoint for a webhook from Account -> Webhooks (EU), read up on how to handle webhook events and check out the API documentation for the details.

Metrics

Metrics offer a high-level view of your account, rolling up those message-level events into summaries for reviewing trends over time. The Reports (EU) section of your SparkPost account provides an easy way to review your sending history. As with most SparkPost features, you can also access these metrics by API call to feed your own applications.

Where To Next?

Beyond the basics, SparkPost also has a slew of additional capabilities which may prove useful. Here are some common follow-on topics to explore.

Email Templates And Personalization

If you’re sending similar content to lots of people, SparkPost templates let you write the message once using substitution variables and logic for personalization, then make a single API call to generate and deliver that message to all your recipients together. You can create and edit templates on your account in the Templates (EU) section. The SparkPost template substitution syntax is explained in the API documentation as well as the relevant API endpoints for managing templates from your own apps.

Service Providers

If you send mail from your SparkPost account on behalf of your own customers and want to keep their activity separate from each other, and from yourself, you should probably consider using subaccounts. You can provision sending domains and API keys on a per-subaccount basis from your account and using the API, as well as retrieving metrics and message events for each subaccount.

Receiving Email

SparkPost can receive email on your behalf and forward to your own HTTP endpoints by using relay webhooks.

How To Get Help

For general questions, you might find a ready-made answer by searching SparkPost’s support articles.

If you run into an issue with your account or the SparkPost service, you can contact our Support team by submitting a ticket through the Support portal. You can also follow the SparkPost status page for service updates.

If you’re interested in chatting with our customers, discussing your integration and getting involved with our developer community, join our Community Slack team.