Getting Started with SparkPost

May 12, 2017 Contributors

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.

Signing Up And In

First things first: sign up for your free SparkPost account here. 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.

Step 1: Creating A Sending Domain

To create your sending domain, visit the Account -> Sending Domains section of your SparkPost account and click the New Domain button. Enter your domain name and click Add Domain.

Adding a sending domain

Step 2: Verifying Domain Ownership

Your new sending domain should now be visible in the Sending Domains list on your account. Before you can send mail using your sending domain, SparkPost needs to verify that you own it.

To do that, you’ll publish a type of DNS record called a DKIM record on your domain and ask SparkPost to check it for you. As a convenient side-effect, that DKIM record will also help your reputation as an email sender. DKIM is useful to your recipients to verify that mail that looks like it came from you was in fact sent by you and it arrived intact.

Note: you will need admin access to your DNS configuration to complete this step.

To generate the DKIM DNS record for your sending domain, click the DKIM record Settings link under your domain on the Sending Domains list. Then use the revealed domain name, record type and value to update your DNS configuration. Each DNS provider has a slightly different interface; you’ll want to create a "TXT" record with the hostname and value SparkPost shows you.

Sending domain DKIM record

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

Once your DKIM DNS record is configured and published, go back to your Sending Domains account settings and click Test under the DKIM settings for your domain. Once SparkPost is able to retrieve your DKIM record, you’ll see a green tick beside the DKIM record section.

Note: DNS changes can take between a few minutes and 24 hours to propagate so a little patience might be required before SparkPost is able to verify your DKIM record.

Alternately, you can verify ownership by receiving an email to an admin account on your domain. From Account -> Sending Domains, the "email options" link under your sending domain will walk you through that process.

Step 3: Compliance Checks

Your domain is now almost ready to send. Once ownership verification completes, your domain will be submitted to our Compliance robots for a few additional checks. Once they complete, you’ll see a green tick beside your domain with the message "Ready to send".

Ready to send

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

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, 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:

Authorization: 0abff4032MYAPIKEY28237aabaddff20758587

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. 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 to review a summary of recipient engagement with your emails. You can also search the message events report in Reports -> Message Events 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:

X-MSYS-API: { "options" : { "open_tracking" : true, "click_tracking" : true } }

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

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 is used by mail software to return undeliverable mail, report on errors and it is also associated with your reputation as a sender.

By default SparkPost uses a generic bounce domain for your email, such as sparkpostmail.com. Setting up a custom bounce domain on your account causes your mail to use a bounce address on your own domain name, such as bounce.myawesomedomain.com. You can create your bounce domain from Account -> Bounce Domains or through the API if you prefer.

Tracking Domain

SparkPost changes each link in your email 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 tracking domains from Account -> Tracking Domains and also through the API.

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 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, 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 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 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.