Sending Domains

A sending domain is a domain that is used to indicate who an email is from via the "From:" header. DNS records can be configured for a sending domain, which allows recipient mail servers to authenticate your messages.

For maximum deliverability, we recommend configuring DKIM for your sending domains and configuring a bounce domain on corresponding subdomains. This is an easy way to help mailbox providers authenticate and differentiate your email from other senders using SparkPost.

DNS notes

DKIM

These requirements are only important to note if you are generating your own DKIM values.

Both PKCS #1 and PKCS #8 formats are supported.
We do not support password-protected keys.
The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.
Public key verification requires the following:
- A valid DKIM record must be in the DNS for the sending domain being verified.
- The record must use the sending domain's public key in the p= tag.
- If a k= tag is defined, it must be set to rsa.
- If an h= tag is defined, it must be set to sha256.

CNAME

CNAME verification requires a valid CNAME record in DNS pointed at the appropriate SparkPost domain.

For SparkPost:

Hostname	Type	Value
example.com	CNAME	sparkpostmail‍.com

For SparkPost EU:

Hostname	Type	Value
example.com	CNAME	eu.sparkpostmail‍.com

For Enterprise accounts:

Hostname	Type	Value
example.‍com	CNAME	<public_tenant_id>.mail.e.sparkpost‍.com

MX verification is only available to Enterprise accounts. Please contact your TAM if you want to verify your domain with MX.

Using a sending domain as a bounce domain

Bounce domains are used to report bounces – emails that were rejected from the recipient server. By setting the bounce domain, you're customizing the address that is used for the Return-Path header, which is the destination for out of band (OOB) bounces.

A sending domain can be used as a bounce domain if it is verified via the following the methods:

CNAME record
MX records (Enterprise only).

Once it is verified through one of those two methods, you can use it as a bounce domain by including it as a transmission's return_path field or SMTP's MAIL FROM email address. For additional details on custom bounce domains, please see this support article.

Sending Domain Object

Example

{
  "domain": "example1.com",
  "tracking_domain": "click.example1.com",
  "status": {
    "ownership_verified": true,
    "spf_status": "unverified",
    "abuse_at_status": "unverified",
    "dkim_status": "valid",
    "cname_status": "valid",
    "mx_status": "unverified",
    "compliance_status": "valid",
    "postmaster_at_status": "unverified",
    "verification_mailbox_status": "valid",
    "verification_mailbox": "susan.calvin"
  },
  "shared_with_subaccounts": false,
  "is_default_bounce_domain": false
}

Attributes

domain string

The domain you are sending from. It will be used in the "From:" header address in emails.

tracking_domain string

Associated tracking domain.

status object

Object containing status details, including whether this domain's ownership has been verified.

dkim object

Object in which DKIM key configuration is defined.

shared_with_subaccounts boolean

Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account.

subaccount_id number

The subaccount ID that the sending domain belongs to. Only available to domains belonging to a subaccount.

is_default_bounce_domain boolean

Whether this domain should be used as the bounce domain when no other valid bounce domain has been specified in the transmission or SMTP injection. Only available to domains with cname_status of "valid" or mx_status of "valid". The primary account as well as each subaccount may set a unique default bounce domain.
Not available for Enterprise accounts.

creation_time string

Datetime the domain was created.
Format: YYYY-MM-DDTHH:MM:SS+-HH:MM

delegated boolean

Whether this domain was delegated to SparkPost by the customer. Will not be present if false.
Only available for Enterprise accounts.

Request

POST /api/v1/sending-domains

{
  "domain": "example1.com",
  "tracking_domain": "click.example1.com",
  "shared_with_subaccounts": false
}

Response

{
  "results": {
    "message": "Successfully Created domain.",
    "domain": "example1.com",
    "dkim": {
      "public": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9OSqnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW1nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQAB",
      "selector": "scph0316",
      "signing_domain": "example1.com",
      "headers": "from:to:subject:date"
    }
  }
}

{
  "errors": [
    {
      "code": "7000",
      "description": "Please contact SparkPost support to get this domain authorized for your account.",
      "message": "Restricted domain"
    }
  ]
}

{
  "errors": [
    {
      "code": "7004",
      "description": "Please contact SparkPost support to check about this org-domain availability.",
      "message": "Domain in use by another account"
    }
  ]
}

{
  "errors": [
    {
      "message": "invalid params",
      "description": "Tracking domain 'click.example1.com' is not a registered tracking domain",
      "code": "1200"
    }
  ]
}

Create a Sending Domain

POST/api/v1/sending-domains

Creates a new sending domain. Each domain and its subdomains can only be added to a single account.

Note: When adding a sending domain to your account, the domain must be verified within two weeks or it will be removed from your account.

Request Body

domain string required

The domain you are sending from.

tracking_domain string

Associated tracking domain. The tracking domain and sending domain must belong to the same subaccount.

dkim object

Object in which DKIM key configuration is defined. Will be generated if generate_dkim is true.

generate_dkim boolean, default is true

Whether to generate a DKIM keypair on creation.

dkim_key_length number, default is 1024

Size, in bits, of the DKIM private key to be generated. This option only applies if generate_dkim is true.
Note public keys for private keys longer than 1024 bits will be longer than 255 characters. Because of this, the public key TXT record in DNS will need to contain multiple strings, see RFC 7208, section 3.3 for an example of how the SPF spec addresses this.

shared_with_subaccounts boolean, default is false

Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account.

Returns the domain and a success message. If generate_dkim was true, the dkim object is also returned.

In case the sending domain gets blocked due to compliance validations, an HTTP 400 response is returned along with the error code, description and message with the reason for the blocking. A few examples are provided in the response section.

Request: Verify DKIM

POST /api/v1/sending-domains/example1.com/verify

{
  "dkim_verify": true
}

Response

{
  "results": {
    "ownership_verified": true,
    "dns": {
      "dkim_record": "k=rsa; h=sha256; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9OSqnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW1nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQAB"
    },
    "dkim_status": "valid",
    "cname_status": "unverified",
    "mx_status": "unverified",
    "compliance_status": "valid",
    "spf_status": "unverified",
    "abuse_at_status": "unverified",
    "postmaster_at_status": "unverified",
    "verification_mailbox_status": "unverified"
  }
}

Request: Initiate anyone@ email

POST /api/v1/sending-domains/example1.com/verify

{
  "verification_mailbox_verify": true,
  "verification_mailbox": "susan.calvin"
}

Response

{
  "results": {
    "ownership_verified": false,
    "spf_status": "unverified",
    "compliance_status": "valid",
    "dkim_status": "unverified",
    "abuse_at_status": "unverified",
    "postmaster_at_status": "unverified",
    "verification_mailbox_status": "unverified",
    "verification_mailbox": "susan.calvin"
  }
}

Verify a Sending Domain

POST/api/v1/sending-domains/{domain}/verify

Parameters

domain string required

Request Body

dkim_verify boolean

Request verification of DKIM record.

cname_verify boolean

Request verification of CNAME record.

verification_mailbox_verify boolean

Request an email with a verification link to be sent to a mailbox on the sending domain. The mailbox is set in the verification_mailbox field. The mailbox can be any valid mailbox for the domain other than "postmaster" or "abuse".
Not available in Enterprise

verification_mailbox string

The nominated mailbox email address local part to be used when requesting email with a verification link be sent. Required if verification_mailbox_verify is true.
Not available in Enterprise

postmaster_at_verify boolean

Request an email with a verification link to be sent to the sending domain's postmaster@ mailbox.

abuse_at_verify boolean

Request an email with a verification link to be sent to the sending domain's abuse@ mailbox.

verification_mailbox_token string

A token retrieved from the verification link contained in the verification email.
Not available in Enterprise

postmaster_at_token string

A token retrieved from the verification link contained in the postmaster@ verification email.

abuse_at_token string

A token retrieved from the verification link contained in the abuse@ verification email.

Enterprise accounts: Depending on your setup, sending domains might be verified automatically when they are created, and can be used to send immediately. In that case, there is no need separately verify sending domains. To find out if this applies to you, ask your TAM.

Verify via DNS

To verify your DKIM or CNAME, include dkim_verify or cname_verify in the request. SparkPost will check against and verify the associated DNS record type for the specified sending domain.

The request will return an extra attribute, dns, which contains the DNS values or error if there was a problem validating the either the DKIM or CNAME.

DNS Object

Attributes

dkim_record string

DNS DKIM record for the registered sending domain

cname_record string

DNS CNAME record for the registered sending domain

dkim_error string

Error message describing reason for DKIM verification failure

cname_error string

Error message describing reason for CNAME verification failure

Verify via mailbox

If you can't update your DNS records for a sending domain, you can verify your domain through a mailbox you control. SparkPost will send an email with a verification link to the specified mailbox. Once the link is clicked, you will be able 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. For this reason, we highly recommend using DNS verification whenever possible.

Trigger a verification email

Including postmaster_at_verify, abuse_at_verify, or verification_mailbox_verify in the request triggers an email sent to the corresponding mailbox with the verification link. When using verification_mailbox_verify, the email is sent to the mailbox set in verification_mailbox.

For postmaster_at_verify, abuse_at_verify and verification_mailbox_verify ownership verification, if the request is made a second time, another email will be sent with a new verification link. If the link in the previously sent message is clicked it won't verify domain ownership.

Validate the verification token

Including verification_mailbox_token, postmaster_at_token, or abuse_at_token in the request checks of the provided token matches the token sent in the email. If it does, the sending domain is verified.

This is handled automatically through the SparkPost app.

Returns

Returns the status object along with the dns property, if dkim_verify or cname_verify was set.

Request

GET /api/v1/sending-domains/example1.com

Response

{
  "results": {
    "tracking_domain": "click.example1.com",
    "status": {
      "ownership_verified": false,
      "spf_status": "unverified",
      "abuse_at_status": "unverified",
      "dkim_status": "unverified",
      "cname_status": "unverified",
      "mx_status": "pending",
      "compliance_status": "valid",
      "postmaster_at_status": "unverified",
      "verification_mailbox_status": "unverified"
    },
    "dkim": {
      "headers": "from:to:subject:date",
      "public": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9OSqnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW1nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQAB",
      "selector": "hello_selector"
    },
    "shared_with_subaccounts": false,
    "is_default_bounce_domain": false
  }
}

Retrieve a Sending Domain

GET/api/v1/sending-domains/{domain}

Parameters

domain string required

Returns the full sending domain object, except the domain field.

Request

PUT /api/v1/sending-domains/example1.com

{
  "tracking_domain": "click.example1.com",
  "dkim": {
    "private": "MIICXgIBAAKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9OSqnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW1nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQABAoGBAITb3BCRPBi5lGhHdn+1RgC7cjUQEbSb4eFHm+ULRwQ0UIPWHwiVWtptZ09usHq989fKp1g/PfcNzm8c78uTS6gCxfECweFCRK6EdO6cCCr1cfWvmBdSjzYhODUdQeyWZi2ozqd0FhGWoV4VHseh4iLj36DzleTLtOZj3FhAo1WJAkEA68T+KkGeDyWwvttYtuSiQCCTrXYAWTQnkIUxduCp7Ap6tVeIDn3TaXTj74UbEgaNgLhjG4bX//fdeDW6PaK9YwJBAM6xJmwHLPMgwNVjiz3u/6fhY3kaZTWcxtMkXCjh1QE82KzDwqyrCg7EFjTtFysSHCAZxXZMcivGl4TZLHnydJUCQQCx16+M+mAatuiCnvxlQUMuMiSTNK6Amzm45u9v53nlZeY3weYMYFdHdfe1pebMiwrT7MI9clKebz6svYJVmdtXAkApDAc8VuR3WB7TgdRKNWdyGJGfoD1PO1ZE4iinOcoKV+IT1UCY99Kkgg6C7j62n/8T5OpRBvd5eBPpHxP1F9BNAkEA5Nf2VO9lcTetksHdIeKK+F7sio6UZn0Rv7iUo3ALrN1D1cGfWIh/Y1g==",
    "public": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9OSqnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW1nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQAB",
    "selector": "hello_selector"
  },
  "is_default_bounce_domain": true
}

Response

{
  "results": {
    "message": "Successfully Updated Domain.",
    "domain": "example1.com"
  }
}

  {
      "errors": [
          {
              "message": "invalid params",
              "description": "Tracking domain '(domain)' is not a registered tracking domain",
              "code": "1200"
          }
      ]
  }

  {
      "errors": [
          {
              "message": "request to remote endpoint failed",
              "description": "Unable to verify DKIM record of example1.com. DNS DKIM query error: 'v=DKIM1;' is missing a p= tag",
              "code": "1404"
          }
      ]
  }

Update a Sending Domain

PUT/api/v1/sending-domains/{domain}

Parameters

domain string required

Request Body

tracking_domain string

Associated tracking domain. To remove the current value, set it to an empty string. The tracking domain and sending domain must belong to the same subaccount.

dkim object

DKIM configuration. Will be verified prior to update. If verification fails, the update will fail.

shared_with_subaccounts boolean

Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account.

is_default_bounce_domain boolean

Whether this domain should be used as the bounce domain when no other valid bounce domain has been specified in the transmission or SMTP injection. Only available to domains with cname_status or mx_status equal to valid. The primary account and each subaccount may set it's own unique default bounce domain.
Not available for Enterprise accounts.

Request

DELETE /api/v1/sending-domains/example1.com

Response

// Empty response body

{
  "errors": [
    {
      "code": "1600",
      "message": "resource not found",
      "description": "Domain 'wrong.domain' does not exist"
    }
  ]
}

Delete a Sending Domain

DELETE/api/v1/sending-domains/{domain}

Parameters

domain string required

Warning: Before deleting a sending domain please ensure you are no longer using it. After deleting a sending domain, any new transmissions that use it will result in a rejection. This includes any transmissions that are in progress, scheduled for the future, or use a stored template referencing the sending domain.

Request

GET /api/v1/sending-domains?ownership_verified=true

Response

{
  "results": [
    {
      "domain": "example1.com",
      "tracking_domain": "click.example1.com",
      "status": {
        "ownership_verified": true,
        "spf_status": "unverified",
        "abuse_at_status": "unverified",
        "dkim_status": "valid",
        "cname_status": "valid",
        "mx_status": "unverified",
        "compliance_status": "valid",
        "postmaster_at_status": "unverified",
        "verification_mailbox_status": "valid",
        "verification_mailbox": "susan.calvin"
      },
      "shared_with_subaccounts": false,
      "is_default_bounce_domain": false
    },
    {
      "domain": "example2.com",
      "status": {
        "ownership_verified": true,
        "spf_status": "unverified",
        "abuse_at_status": "unverified",
        "dkim_status": "valid",
        "cname_status": "valid",
        "mx_status": "unverified",
        "compliance_status": "valid",
        "postmaster_at_status": "unverified",
        "verification_mailbox_status": "unverified"
      },
      "shared_with_subaccounts": false,
      "is_default_bounce_domain": false
    }
  ]
}

List all Sending Domains

GET/api/v1/sending-domains{?ownership_verified,dkim_status,cname_status,mx_status,abuse_at_status,postmaster_at_status,compliance_status,is_default_bounce_domain}

Parameters

ownership_verified boolean

Ownership verified filter. Valid values are true or false.

dkim_status enum

DKIM status filter.