# 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/email-api/sending-domains.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.