SparkPost

Authentication & Authorization

Credentials

• SparkPost connects via API key.
• API key is set with the Authorization request header.
• API keys can be created and managed in the SparkPost application. See SparkPost Connection Instructions.
• Publicly exposing your API keys can allow unauthorized access to the SparkPost API endpoints, and your SparkPost data by a third party. DataGrail stores your API keys encrypted and protected.

Permissions

API key should be configured with permissions to limit DataGrail access to certain SparkPost API calls. See SparkPost Connection Instructions.

The next permissions are required and should be set to connect DataGrail integration:

• Account: Read
• Suppression Lists: Read/Write

Additionally, depending on the required integration capabilities, DataGrail requires the following permissions to be set:

Access

• Events Search: Read-only
• Recipient Lists: Read/Write

Deletion

• Data Privacy: Read/Write
• Recipient Lists: Read/Write

Do Not Sell

• Data Privacy: Read/Write

Transaction Mailer

• Transmissions: Read/Write

Base URL

The base URL dependents on the customer’s SparkPost hosting:

• SparkPost: https:​//api.sparkpost.com/api/v1
• SparkPost EU: https:​//api.eu.sparkpost.com/api/v1

An account created in SparkPost cannot be used in SparkPost EU, and vice-versa.

Endpoints Utilized

DataGrail uses the following endpoint to verify API connection:

• POST {BASE_URL}/suppression-list/summary

Version

DataGrail SparkPost integration currently supports API version 1 (v1).

Limits

SparkPost APIs are rate limited, which limits how often each user can call the API, in order to protect the service from inadvertent or malicious overuse.

DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

Access

For an access request, DataGrail will take the following actions:

• Retrieve account information to check is SparkPost account or sub-account connected.
• Fetch all recipient lists.
• Retrieve each of recipient list.
• Filter recipients by the Data Subject email.
• Search message events by the Data Subject email.
• Search suppressions by the Data Subject email.
• For all objects found, DataGrail will return all available fields. You can edit which objects and fields you want to provide to the Data Subject via our Portal Requests.

DataGrail also supports the Direct Contact Access workflow for SparkPost.

Endpoints Utilized

• GET {BASE_URL}/account
• GET {BASE_URL}/recipient-lists
• GET {BASE_URL}/recipient-lists/{list_id}
• GET {BASE_URL}/events/message
• GET {BASE_URL}/suppression-list/{recipient_email}

Deletion

For a deletion request, DataGrail will take the following actions:

• Send request to be forgotten the Data Subject recipient email.
• Start scheduling task for regular checking presents the Data Subject recipient email under the customer's SparkPost account:
  • Fetch all recipient lists.
  • Retrieve each of recipient list.
  • Search recipients by the Data Subject email.
• Complete deletion process as soon recipients with the Data Subject email not found.

DataGrail also supports the Direct Contact Deletion workflow for SparkPost.

Endpoints Utilized

• POST {BASE_URL}/data-privacy/rtbf-request
• GET {BASE_URL}/recipient-lists
• GET {BASE_URL}/recipient-lists/{list_id}

Do Not Sell

For a Do Not Sell request, DataGrail will take the following actions:

• Send opt out request for the Data Subject recipient email.

Endpoints Utilized

• POST {BASE_URL}/data-privacy/opt-out-request

Transaction Mailer

SparkPost integration can be configured as DataGrail Transactional Mailer.

In this mode, DataGrail uses SparkPost integration to send emails via create a transmission requests, using pre-configured Return Path. The domain of the Return Path address must be a CNAME-verified sending domain (see SparkPost Connection Instructions).

Note: For Enterprise SparkPost accounts, the Return Path may be any valid email address and don't need t obe configured on the DataGrail side.

Endpoints Utilized

• POST {BASE_URL}/transmissions