> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/email-api/sending-domains.md).

# 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-1.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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).

## List all Sending Domains

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

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Sending Domains","description":"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.\n\n**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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n### DNS notes\n\n**DKIM**\n\nThese requirements are only important to note if you are generating your own DKIM values.\n\n* Both PKCS #1 and PKCS #8 formats are supported.\n* We do not support password-protected keys.\n* The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.\n* Public key verification requires the following:\n    * A valid DKIM record must be in the DNS for the sending domain being verified.\n    * The record must use the sending domain's public key in the `p=` tag.\n    * If a `k=` tag is defined, it must be set to `rsa`.\n    * If an `h=` tag is defined, it must be set to `sha256`.\n\n**CNAME**\n\nCNAME verification requires a valid CNAME record in DNS pointed at the appropriate Bird domain.\n\nFor workspaces located in the US:\n\n| Hostname    | Type  | Value                  |\n|-------------|-------|------------------------|\n| example.com | CNAME | sparkpostmail&zwj;.com |\n\n\nFor workspaces located in the EU:\n\n| Hostname    | Type  | Value                     |\n|-------------|-------|---------------------------|\n| example.com | CNAME | eu.sparkpostmail&zwj;.com |\n\n\nFor Enterprise accounts:\n\n| Hostname         | Type  | Value                                        |\n|------------------|-------|----------------------------------------------|\n| example.&zwj;com | CNAME | <public_tenant_id>.mail.e.sparkpost&zwj;.com |\n\n**MX**\n\nMX verification is only available to <strong>Enterprise</strong> accounts. Please contact your TAM if you want to verify your domain with MX.\n\n\n### Using a sending domain as a bounce domain\n\nBounce 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.\n\nA sending domain can be used as a bounce domain if it is verified via the following the methods:\n* CNAME record\n* MX records (<span class=\"label label-warning\"><strong>Enterprise</strong></span> only).\n\nOnce 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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"ListSendingDomainsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SendingDomain"}}}},"SendingDomain":{"type":"object","properties":{"domain":{"type":"string","description":"The domain you are sending from. It will be used in the \"From:\" header address in emails."},"tracking_domain":{"type":"string","description":"Associated tracking domain."},"status":{"$ref":"#/components/schemas/SendingDomainStatus"},"dkim":{"$ref":"#/components/schemas/DkimConfiguration"},"shared_with_subaccounts":{"type":"boolean","description":"Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account."},"subaccount_id":{"type":"number","description":"The subaccount ID that the sending domain belongs to. Only available to domains belonging to a subaccount."},"is_default_bounce_domain":{"type":"boolean","description":"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."},"creation_time":{"type":"string","format":"date-time","description":"Datetime the domain was created."},"delegated":{"type":"boolean","description":"Whether this domain was delegated to Bird by the customer. Will not be present if false. Only available for Enterprise accounts."}}},"SendingDomainStatus":{"type":"object","properties":{"ownership_verified":{"type":"boolean","description":"Whether domain ownership has been verified. This field will return `true` if any of the following status fields are valid.","default":false},"dkim_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of DKIM configuration.","default":"unverified"},"cname_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of CNAME configuration.","default":"unverified"},"mx_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of MX configuration. Only available for Enterprise accounts.","default":"unverified"},"spf_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"[Deprecated] Verification status of SPF configuration.","default":"unverified"},"abuse_at_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of abuse@ mailbox.","default":"unverified"},"postmaster_at_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of postmaster@ mailbox.","default":"unverified"},"verification_mailbox_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of nominated anyone@ mailbox.","default":"unverified"},"verification_mailbox":{"type":"string","description":"Nominated anyone@ verification mailbox email address local part."},"compliance_status":{"type":"string","enum":["valid","blocked"],"description":"Compliance status"}}},"DkimConfiguration":{"type":"object","properties":{"signing_domain":{"type":"string","description":"Value used as the Signing Domain Identifier (SDID). Only writable by Enterprise accounts."},"public":{"type":"string","description":"Value used as the public key which will be retrieved from the DNS of the sending domain."},"private":{"type":"string","description":"Value used as the private key which will be used to create the DKIM Signature."},"selector":{"type":"string","description":"Value used as the DomainKey selector which indicates the DKIM public key location."},"headers":{"type":"string","description":"Header fields to be included in the DKIM signature. This field is currently ignored."}}}}},"paths":{"/workspaces/{workspaceId}/reach/sending-domains":{"get":{"tags":["Sending Domains"],"summary":"List all Sending Domains","description":"Returns an array with all the sending domains in your account. Use the query parameters to filter on the various status options.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"ownership_verified","in":"query","description":"Ownership verified filter","schema":{"type":"boolean"}},{"name":"dkim_status","in":"query","description":"DKIM status filter","schema":{"type":"string","enum":["valid","invalid","unverified","pending"]}},{"name":"cname_status","in":"query","description":"CNAME status filter","schema":{"type":"string","enum":["valid","invalid","unverified","pending"]}},{"name":"mx_status","in":"query","description":"MX status filter","schema":{"type":"string","enum":["valid","invalid","unverified","pending"]}},{"name":"abuse_at_status","in":"query","description":"abuse@ status filter","schema":{"type":"string","enum":["valid","invalid","unverified","pending"]}},{"name":"postmaster_at_status","in":"query","description":"postmaster@ status filter","schema":{"type":"string","enum":["valid","invalid","unverified","pending"]}},{"name":"compliance_status","in":"query","description":"Compliance status filter","schema":{"type":"string","enum":["valid","blocked"]}},{"name":"is_default_bounce_domain","in":"query","description":"Is default bounce domain filter","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved sending domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSendingDomainsResponse"}}}}}}}}}
```

## Create a Sending Domain

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

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Sending Domains","description":"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.\n\n**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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n### DNS notes\n\n**DKIM**\n\nThese requirements are only important to note if you are generating your own DKIM values.\n\n* Both PKCS #1 and PKCS #8 formats are supported.\n* We do not support password-protected keys.\n* The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.\n* Public key verification requires the following:\n    * A valid DKIM record must be in the DNS for the sending domain being verified.\n    * The record must use the sending domain's public key in the `p=` tag.\n    * If a `k=` tag is defined, it must be set to `rsa`.\n    * If an `h=` tag is defined, it must be set to `sha256`.\n\n**CNAME**\n\nCNAME verification requires a valid CNAME record in DNS pointed at the appropriate Bird domain.\n\nFor workspaces located in the US:\n\n| Hostname    | Type  | Value                  |\n|-------------|-------|------------------------|\n| example.com | CNAME | sparkpostmail&zwj;.com |\n\n\nFor workspaces located in the EU:\n\n| Hostname    | Type  | Value                     |\n|-------------|-------|---------------------------|\n| example.com | CNAME | eu.sparkpostmail&zwj;.com |\n\n\nFor Enterprise accounts:\n\n| Hostname         | Type  | Value                                        |\n|------------------|-------|----------------------------------------------|\n| example.&zwj;com | CNAME | <public_tenant_id>.mail.e.sparkpost&zwj;.com |\n\n**MX**\n\nMX verification is only available to <strong>Enterprise</strong> accounts. Please contact your TAM if you want to verify your domain with MX.\n\n\n### Using a sending domain as a bounce domain\n\nBounce 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.\n\nA sending domain can be used as a bounce domain if it is verified via the following the methods:\n* CNAME record\n* MX records (<span class=\"label label-warning\"><strong>Enterprise</strong></span> only).\n\nOnce 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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"CreateSendingDomainRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"The domain you are sending from."},"tracking_domain":{"type":"string","description":"Associated tracking domain. The tracking domain and sending domain must belong to the same subaccount."},"dkim":{"$ref":"#/components/schemas/DkimConfiguration"},"generate_dkim":{"type":"boolean","description":"Whether to generate a DKIM keypair on creation.","default":true},"dkim_key_length":{"type":"number","description":"Size, in bits, of the DKIM private key to be generated. This option only applies if `generate_dkim` is true.","default":1024},"shared_with_subaccounts":{"type":"boolean","description":"Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account.","default":false}}},"DkimConfiguration":{"type":"object","properties":{"signing_domain":{"type":"string","description":"Value used as the Signing Domain Identifier (SDID). Only writable by Enterprise accounts."},"public":{"type":"string","description":"Value used as the public key which will be retrieved from the DNS of the sending domain."},"private":{"type":"string","description":"Value used as the private key which will be used to create the DKIM Signature."},"selector":{"type":"string","description":"Value used as the DomainKey selector which indicates the DKIM public key location."},"headers":{"type":"string","description":"Header fields to be included in the DKIM signature. This field is currently ignored."}}},"CreateSendingDomainResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"message":{"type":"string"},"domain":{"type":"string"},"dkim":{"$ref":"#/components/schemas/DkimConfiguration"}}}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine readable error code"},"message":{"type":"string","description":"Human readable error message"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/sending-domains":{"post":{"tags":["Sending Domains"],"summary":"Create a Sending Domain","description":"Creates a new sending domain. Each domain and its subdomains can only be added to a single account.\n\n**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.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSendingDomainRequest"}}}},"responses":{"200":{"description":"Successfully created domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSendingDomainResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Retrieve a Sending Domain

> Returns the full sending domain object, except the \`domain\` field.

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Sending Domains","description":"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.\n\n**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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n### DNS notes\n\n**DKIM**\n\nThese requirements are only important to note if you are generating your own DKIM values.\n\n* Both PKCS #1 and PKCS #8 formats are supported.\n* We do not support password-protected keys.\n* The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.\n* Public key verification requires the following:\n    * A valid DKIM record must be in the DNS for the sending domain being verified.\n    * The record must use the sending domain's public key in the `p=` tag.\n    * If a `k=` tag is defined, it must be set to `rsa`.\n    * If an `h=` tag is defined, it must be set to `sha256`.\n\n**CNAME**\n\nCNAME verification requires a valid CNAME record in DNS pointed at the appropriate Bird domain.\n\nFor workspaces located in the US:\n\n| Hostname    | Type  | Value                  |\n|-------------|-------|------------------------|\n| example.com | CNAME | sparkpostmail&zwj;.com |\n\n\nFor workspaces located in the EU:\n\n| Hostname    | Type  | Value                     |\n|-------------|-------|---------------------------|\n| example.com | CNAME | eu.sparkpostmail&zwj;.com |\n\n\nFor Enterprise accounts:\n\n| Hostname         | Type  | Value                                        |\n|------------------|-------|----------------------------------------------|\n| example.&zwj;com | CNAME | <public_tenant_id>.mail.e.sparkpost&zwj;.com |\n\n**MX**\n\nMX verification is only available to <strong>Enterprise</strong> accounts. Please contact your TAM if you want to verify your domain with MX.\n\n\n### Using a sending domain as a bounce domain\n\nBounce 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.\n\nA sending domain can be used as a bounce domain if it is verified via the following the methods:\n* CNAME record\n* MX records (<span class=\"label label-warning\"><strong>Enterprise</strong></span> only).\n\nOnce 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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"GetSendingDomainResponse":{"type":"object","properties":{"results":{"allOf":[{"$ref":"#/components/schemas/SendingDomain"},{"type":"object","properties":{"domain":{"type":"string","nullable":true}}}]}}},"SendingDomain":{"type":"object","properties":{"domain":{"type":"string","description":"The domain you are sending from. It will be used in the \"From:\" header address in emails."},"tracking_domain":{"type":"string","description":"Associated tracking domain."},"status":{"$ref":"#/components/schemas/SendingDomainStatus"},"dkim":{"$ref":"#/components/schemas/DkimConfiguration"},"shared_with_subaccounts":{"type":"boolean","description":"Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account."},"subaccount_id":{"type":"number","description":"The subaccount ID that the sending domain belongs to. Only available to domains belonging to a subaccount."},"is_default_bounce_domain":{"type":"boolean","description":"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."},"creation_time":{"type":"string","format":"date-time","description":"Datetime the domain was created."},"delegated":{"type":"boolean","description":"Whether this domain was delegated to Bird by the customer. Will not be present if false. Only available for Enterprise accounts."}}},"SendingDomainStatus":{"type":"object","properties":{"ownership_verified":{"type":"boolean","description":"Whether domain ownership has been verified. This field will return `true` if any of the following status fields are valid.","default":false},"dkim_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of DKIM configuration.","default":"unverified"},"cname_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of CNAME configuration.","default":"unverified"},"mx_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of MX configuration. Only available for Enterprise accounts.","default":"unverified"},"spf_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"[Deprecated] Verification status of SPF configuration.","default":"unverified"},"abuse_at_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of abuse@ mailbox.","default":"unverified"},"postmaster_at_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of postmaster@ mailbox.","default":"unverified"},"verification_mailbox_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of nominated anyone@ mailbox.","default":"unverified"},"verification_mailbox":{"type":"string","description":"Nominated anyone@ verification mailbox email address local part."},"compliance_status":{"type":"string","enum":["valid","blocked"],"description":"Compliance status"}}},"DkimConfiguration":{"type":"object","properties":{"signing_domain":{"type":"string","description":"Value used as the Signing Domain Identifier (SDID). Only writable by Enterprise accounts."},"public":{"type":"string","description":"Value used as the public key which will be retrieved from the DNS of the sending domain."},"private":{"type":"string","description":"Value used as the private key which will be used to create the DKIM Signature."},"selector":{"type":"string","description":"Value used as the DomainKey selector which indicates the DKIM public key location."},"headers":{"type":"string","description":"Header fields to be included in the DKIM signature. This field is currently ignored."}}}}},"paths":{"/workspaces/{workspaceId}/reach/sending-domains/{domain}":{"get":{"tags":["Sending Domains"],"summary":"Retrieve a Sending Domain","description":"Returns the full sending domain object, except the `domain` field.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain","in":"path","required":true,"description":"The sending domain name","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved sending domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSendingDomainResponse"}}}}}}}}}
```

## Update a Sending Domain

> Updates an existing sending domain.

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Sending Domains","description":"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.\n\n**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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n### DNS notes\n\n**DKIM**\n\nThese requirements are only important to note if you are generating your own DKIM values.\n\n* Both PKCS #1 and PKCS #8 formats are supported.\n* We do not support password-protected keys.\n* The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.\n* Public key verification requires the following:\n    * A valid DKIM record must be in the DNS for the sending domain being verified.\n    * The record must use the sending domain's public key in the `p=` tag.\n    * If a `k=` tag is defined, it must be set to `rsa`.\n    * If an `h=` tag is defined, it must be set to `sha256`.\n\n**CNAME**\n\nCNAME verification requires a valid CNAME record in DNS pointed at the appropriate Bird domain.\n\nFor workspaces located in the US:\n\n| Hostname    | Type  | Value                  |\n|-------------|-------|------------------------|\n| example.com | CNAME | sparkpostmail&zwj;.com |\n\n\nFor workspaces located in the EU:\n\n| Hostname    | Type  | Value                     |\n|-------------|-------|---------------------------|\n| example.com | CNAME | eu.sparkpostmail&zwj;.com |\n\n\nFor Enterprise accounts:\n\n| Hostname         | Type  | Value                                        |\n|------------------|-------|----------------------------------------------|\n| example.&zwj;com | CNAME | <public_tenant_id>.mail.e.sparkpost&zwj;.com |\n\n**MX**\n\nMX verification is only available to <strong>Enterprise</strong> accounts. Please contact your TAM if you want to verify your domain with MX.\n\n\n### Using a sending domain as a bounce domain\n\nBounce 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.\n\nA sending domain can be used as a bounce domain if it is verified via the following the methods:\n* CNAME record\n* MX records (<span class=\"label label-warning\"><strong>Enterprise</strong></span> only).\n\nOnce 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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"UpdateSendingDomainRequest":{"type":"object","properties":{"tracking_domain":{"type":"string","description":"Associated tracking domain. To remove the current value, set it to an empty string."},"dkim":{"$ref":"#/components/schemas/DkimConfiguration"},"shared_with_subaccounts":{"type":"boolean","description":"Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account."},"is_default_bounce_domain":{"type":"boolean","description":"Whether this domain should be used as the bounce domain when no other valid bounce domain has been specified."}}},"DkimConfiguration":{"type":"object","properties":{"signing_domain":{"type":"string","description":"Value used as the Signing Domain Identifier (SDID). Only writable by Enterprise accounts."},"public":{"type":"string","description":"Value used as the public key which will be retrieved from the DNS of the sending domain."},"private":{"type":"string","description":"Value used as the private key which will be used to create the DKIM Signature."},"selector":{"type":"string","description":"Value used as the DomainKey selector which indicates the DKIM public key location."},"headers":{"type":"string","description":"Header fields to be included in the DKIM signature. This field is currently ignored."}}},"UpdateSendingDomainResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"message":{"type":"string"},"domain":{"type":"string"}}}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine readable error code"},"message":{"type":"string","description":"Human readable error message"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/sending-domains/{domain}":{"put":{"tags":["Sending Domains"],"summary":"Update a Sending Domain","description":"Updates an existing sending domain.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain","in":"path","required":true,"description":"The sending domain name","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSendingDomainRequest"}}}},"responses":{"200":{"description":"Successfully updated domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSendingDomainResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a Sending 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.<br>

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Sending Domains","description":"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.\n\n**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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n### DNS notes\n\n**DKIM**\n\nThese requirements are only important to note if you are generating your own DKIM values.\n\n* Both PKCS #1 and PKCS #8 formats are supported.\n* We do not support password-protected keys.\n* The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.\n* Public key verification requires the following:\n    * A valid DKIM record must be in the DNS for the sending domain being verified.\n    * The record must use the sending domain's public key in the `p=` tag.\n    * If a `k=` tag is defined, it must be set to `rsa`.\n    * If an `h=` tag is defined, it must be set to `sha256`.\n\n**CNAME**\n\nCNAME verification requires a valid CNAME record in DNS pointed at the appropriate Bird domain.\n\nFor workspaces located in the US:\n\n| Hostname    | Type  | Value                  |\n|-------------|-------|------------------------|\n| example.com | CNAME | sparkpostmail&zwj;.com |\n\n\nFor workspaces located in the EU:\n\n| Hostname    | Type  | Value                     |\n|-------------|-------|---------------------------|\n| example.com | CNAME | eu.sparkpostmail&zwj;.com |\n\n\nFor Enterprise accounts:\n\n| Hostname         | Type  | Value                                        |\n|------------------|-------|----------------------------------------------|\n| example.&zwj;com | CNAME | <public_tenant_id>.mail.e.sparkpost&zwj;.com |\n\n**MX**\n\nMX verification is only available to <strong>Enterprise</strong> accounts. Please contact your TAM if you want to verify your domain with MX.\n\n\n### Using a sending domain as a bounce domain\n\nBounce 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.\n\nA sending domain can be used as a bounce domain if it is verified via the following the methods:\n* CNAME record\n* MX records (<span class=\"label label-warning\"><strong>Enterprise</strong></span> only).\n\nOnce 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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine readable error code"},"message":{"type":"string","description":"Human readable error message"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/sending-domains/{domain}":{"delete":{"tags":["Sending Domains"],"summary":"Delete a Sending Domain","description":"**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.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain","in":"path","required":true,"description":"The sending domain name","schema":{"type":"string"}}],"responses":{"204":{"description":"Successfully deleted domain"},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Verify a Sending Domain

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

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Sending Domains","description":"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.\n\n**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.\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n### DNS notes\n\n**DKIM**\n\nThese requirements are only important to note if you are generating your own DKIM values.\n\n* Both PKCS #1 and PKCS #8 formats are supported.\n* We do not support password-protected keys.\n* The DKIM public/private key pair must match a single format as the API will reject mismatching pairs.\n* Public key verification requires the following:\n    * A valid DKIM record must be in the DNS for the sending domain being verified.\n    * The record must use the sending domain's public key in the `p=` tag.\n    * If a `k=` tag is defined, it must be set to `rsa`.\n    * If an `h=` tag is defined, it must be set to `sha256`.\n\n**CNAME**\n\nCNAME verification requires a valid CNAME record in DNS pointed at the appropriate Bird domain.\n\nFor workspaces located in the US:\n\n| Hostname    | Type  | Value                  |\n|-------------|-------|------------------------|\n| example.com | CNAME | sparkpostmail&zwj;.com |\n\n\nFor workspaces located in the EU:\n\n| Hostname    | Type  | Value                     |\n|-------------|-------|---------------------------|\n| example.com | CNAME | eu.sparkpostmail&zwj;.com |\n\n\nFor Enterprise accounts:\n\n| Hostname         | Type  | Value                                        |\n|------------------|-------|----------------------------------------------|\n| example.&zwj;com | CNAME | <public_tenant_id>.mail.e.sparkpost&zwj;.com |\n\n**MX**\n\nMX verification is only available to <strong>Enterprise</strong> accounts. Please contact your TAM if you want to verify your domain with MX.\n\n\n### Using a sending domain as a bounce domain\n\nBounce 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.\n\nA sending domain can be used as a bounce domain if it is verified via the following the methods:\n* CNAME record\n* MX records (<span class=\"label label-warning\"><strong>Enterprise</strong></span> only).\n\nOnce 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](https://www.sparkpost.com/docs/tech-resources/custom-bounce-domain/).\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"VerifySendingDomainRequest":{"type":"object","properties":{"dkim_verify":{"type":"boolean","description":"Request verification of DKIM record."},"cname_verify":{"type":"boolean","description":"Request verification of CNAME record."},"verification_mailbox_verify":{"type":"boolean","description":"Request an email with a verification link to be sent to a mailbox on the sending domain."},"verification_mailbox":{"type":"string","description":"The nominated mailbox email address local part to be used when requesting email with a verification link be sent."},"postmaster_at_verify":{"type":"boolean","description":"Request an email with a verification link to be sent to the sending domain's postmaster@ mailbox."},"abuse_at_verify":{"type":"boolean","description":"Request an email with a verification link to be sent to the sending domain's abuse@ mailbox."},"verification_mailbox_token":{"type":"string","description":"A token retrieved from the verification link contained in the verification email."},"postmaster_at_token":{"type":"string","description":"A token retrieved from the verification link contained in the postmaster@ verification email."},"abuse_at_token":{"type":"string","description":"A token retrieved from the verification link contained in the abuse@ verification email."}}},"VerifySendingDomainResponse":{"type":"object","properties":{"results":{"allOf":[{"$ref":"#/components/schemas/SendingDomainStatus"},{"type":"object","properties":{"dns":{"$ref":"#/components/schemas/DnsVerificationData"}}}]}}},"SendingDomainStatus":{"type":"object","properties":{"ownership_verified":{"type":"boolean","description":"Whether domain ownership has been verified. This field will return `true` if any of the following status fields are valid.","default":false},"dkim_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of DKIM configuration.","default":"unverified"},"cname_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of CNAME configuration.","default":"unverified"},"mx_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of MX configuration. Only available for Enterprise accounts.","default":"unverified"},"spf_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"[Deprecated] Verification status of SPF configuration.","default":"unverified"},"abuse_at_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of abuse@ mailbox.","default":"unverified"},"postmaster_at_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of postmaster@ mailbox.","default":"unverified"},"verification_mailbox_status":{"type":"string","enum":["unverified","pending","invalid","valid"],"description":"Verification status of nominated anyone@ mailbox.","default":"unverified"},"verification_mailbox":{"type":"string","description":"Nominated anyone@ verification mailbox email address local part."},"compliance_status":{"type":"string","enum":["valid","blocked"],"description":"Compliance status"}}},"DnsVerificationData":{"type":"object","properties":{"dkim_record":{"type":"string","description":"DNS DKIM record for the registered sending domain"},"cname_record":{"type":"string","description":"DNS CNAME record for the registered sending domain"},"dkim_error":{"type":"string","description":"Error message describing reason for DKIM verification failure"},"cname_error":{"type":"string","description":"Error message describing reason for CNAME verification failure"}}}}},"paths":{"/workspaces/{workspaceId}/reach/sending-domains/{domain}/verify":{"post":{"tags":["Sending Domains"],"summary":"Verify a Sending Domain","description":"Verify a sending domain through various methods including DNS verification (DKIM/CNAME) or email verification.\n\n### Verify via DNS\nTo 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.\n\n### Verify via mailbox\nIf 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.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"domain","in":"path","required":true,"description":"The sending domain name","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySendingDomainRequest"}}}},"responses":{"200":{"description":"Successfully processed verification request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySendingDomainResponse"}}}}}}}}}
```