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

Regional Endpoints

Please use the appropriate API endpoint based on your workspace region:

• EU workspaces: https://email.eu-west-1.api.bird.com

• US workspaces: https://email.us-west-2.api.bird.com

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

For workspaces located in the US:

Hostname	Type	Value
example.com	CNAME	sparkpostmail‍.com

For workspaces located in the 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

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.

List all Sending Domains

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/sending-domains

Returns an array with all the sending domains in your account. Use the query parameters to filter on the various status options.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

ownership_verifiedbooleanOptional

Ownership verified filter

dkim_statusstring · enumOptional

DKIM status filter

Possible values:

cname_statusstring · enumOptional

CNAME status filter

Possible values:

mx_statusstring · enumOptional

MX status filter

Possible values:

abuse_at_statusstring · enumOptional

abuse@ status filter

Possible values:

postmaster_at_statusstring · enumOptional

postmaster@ status filter

Possible values:

compliance_statusstring · enumOptional

Compliance status filter

Possible values:

is_default_bounce_domainbooleanOptional

Is default bounce domain filter

Responses

200

Successfully retrieved sending domains

application/json

get

/workspaces/{workspaceId}/reach/sending-domains

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/sending-domains HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved sending domains

{
  "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
    }
  ]
}

Create a Sending Domain

post

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Body

application/json

domainstringRequired

The domain you are sending from.

Example: example1.com

tracking_domainstringOptional

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

Example: click.example1.com

generate_dkimbooleanOptional

Whether to generate a DKIM keypair on creation.

Default: true

dkim_key_lengthnumberOptional

Size, in bits, of the DKIM private key to be generated. This option only applies if generate_dkim is true.

Default: 1024

shared_with_subaccountsbooleanOptional

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

Default: false

Responses

200

Successfully created domain

application/json

400

Bad Request

application/json

post

/workspaces/{workspaceId}/reach/sending-domains

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/sending-domains HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 96

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

{
  "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"
    }
  }
}

Retrieve a Sending Domain

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/sending-domains/{domain}

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

domainstringRequired

The sending domain name

Example: example1.com

Responses

200

Successfully retrieved sending domain

application/json

get

/workspaces/{workspaceId}/reach/sending-domains/{domain}

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/sending-domains/{domain} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved sending domain

{
  "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
  }
}

Update a Sending Domain

put

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/sending-domains/{domain}

Updates an existing sending domain.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

domainstringRequired

The sending domain name

Example: example1.com

Body

application/json

tracking_domainstringOptional

Associated tracking domain. To remove the current value, set it to an empty string.

shared_with_subaccountsbooleanOptional

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

is_default_bounce_domainbooleanOptional

Whether this domain should be used as the bounce domain when no other valid bounce domain has been specified.

Responses

200

Successfully updated domain

application/json

400

Bad Request

application/json

put

/workspaces/{workspaceId}/reach/sending-domains/{domain}

HTTPcURLJavaScriptPython

PUT /api/workspaces/{workspaceId}/reach/sending-domains/{domain} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1135

{
  "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
}

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

Delete a Sending Domain

delete

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/sending-domains/{domain}

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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

domainstringRequired

The sending domain name

Example: example1.com

Responses

204

Successfully deleted domain

404

Domain not found

application/json

delete

/workspaces/{workspaceId}/reach/sending-domains/{domain}

HTTPcURLJavaScriptPython

DELETE /api/workspaces/{workspaceId}/reach/sending-domains/{domain} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

No content

Verify a Sending Domain

post

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-2.api.bird.com/api

/workspaces/{workspaceId}/reach/sending-domains/{domain}/verify

Verify a sending domain through various methods including DNS verification (DKIM/CNAME) or email verification.

Verify via DNS

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

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. Bird will send an email with a verification link to the specified mailbox.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

domainstringRequired

The sending domain name

Example: example1.com

Body

application/json

dkim_verifybooleanOptional

Request verification of DKIM record.

cname_verifybooleanOptional

Request verification of CNAME record.

verification_mailbox_verifybooleanOptional

Request an email with a verification link to be sent to a mailbox on the sending domain.

verification_mailboxstringOptional

The nominated mailbox email address local part to be used when requesting email with a verification link be sent.

postmaster_at_verifybooleanOptional

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

abuse_at_verifybooleanOptional

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

verification_mailbox_tokenstringOptional

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

postmaster_at_tokenstringOptional

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

abuse_at_tokenstringOptional

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

Responses

200

Successfully processed verification request

application/json

post

/workspaces/{workspaceId}/reach/sending-domains/{domain}/verify

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/sending-domains/{domain}/verify HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "dkim_verify": true
}

Verify DKIMInitiate anyone@ email verification

200

Successfully processed verification request

{
  "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"
  }
}