Bounce Domains

The Bounce Domains endpoint is deprecated. Please use the Sending Domains endpoint to configure one or more CNAME-verified domains to be used as custom bounce domains.

Note: Only one custom bounce domain is permitted per account via the Bounce Domains API. Please use the Sending Domains API to configure multiple bounce domains.

Bounce domains are used to report bounces, which are emails that were rejected from the recipient server. By adding a custom bounce domain to your account, you can customize the address that is used for the Return-Path header, which is the destination for out of band (OOB) bounces. This custom bounce domain overrides the default Return-Path (also known as the envelope FROM) for all messages sent. The default bounce domain is similar to "sparkpostmail.com".

Note: Use of a bounce domain requires adding a CNAME record to your DNS. See this support article for details.
SparkPost Enterprise customers, your TAM will handle this for you.

Using Postman

If you use Postman you can click the following button to import the SparkPost API as a collection:

Run in Postman

Bounce Domains Attributes

Field Type Description Required Notes
domain string Name of the bounce domain yes Example: example.domain.com
status JSON object JSON object containing status details, including whether this domain’s ownership has been verified no Read only. For a full description, see the Status Attributes.

Status Attributes

Detailed status for this bounce domain is described in a JSON object with the following fields:

Field Type Description Default Notes
verified boolean Whether domain has been verified false Read only. This field will return “true” if cname_status is “valid”.
cname_status string Verification status of CNAME configuration unverified Read only. Valid values are “unverified”, “pending”, “invalid” or “valid”.
compliance_status string Compliance status Valid values are “pending”, “valid”, or “blocked”.

Create and List

Create a Bounce Domain

POST/api/v1/bounce-domains

Create a Bounce Domain.

Note: Only one custom bounce domain is permitted per account at this time.

Examples

Request

POST /api/v1/bounce-domains

{
  "domain": "example.domain.com"
}

Response (HTTP status code: 200)

{
  "results": {
    "domain": "example.domain.com"
  }
}

Response (HTTP status code: 400)

{
  "errors": [
    {
      "code": "8000",
      "message": "only one bounce domain can be created",
      "description": "Can't create more than one bounce domain."
    }
  ]
}

Response (HTTP status code: 400)

{
  "errors": [
    {
      "code": "7000",
      "message": "restricted domain",
      "description": "Please contact us at support@sparkpost.com to get this domain authorized for your account."
    }
  ]
}

Response (HTTP status code: 409)

{
  "errors": [
    {
      "code": "1602",
      "message": "resource conflict",
      "description": "A bounce domain with similar attributes already exists."
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error validating domain name syntax for domain: 'example..domain.com'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error domain name length too short for domain: 'ex'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error domain name contains no '.'(s) for domain: 'exampledomaincom'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error domain name contains invalid characters or spaces for domain: 'example*&#.domain.com'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1400",
      "message": "required field is missing",
      "description": "Missing required field: (domain) is required"
    }
  ]
}

List Bounce Domains

GET/api/v1/bounce-domains

Retrieve a list of all bounce domains.

Note: Only one custom bounce domain is permitted per account at this time.

Examples

Request

GET /api/v1/bounce-domains

Response (HTTP status code: 200)

{
  "results": [
    {
      "domain": "example.domain.com",
      "status": {
        "verified": false,
        "cname_status": "pending",
        "compliance_status": "pending"
      }
    }
  ]
}

Retrieve and Delete

Retrieve a Bounce Domain

GET/api/v1/bounce-domains/{domain}
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Retrieve an existing bounce domain.

Examples

Request

GET /api/v1/bounce-domains/example.domain.com

Response (HTTP status code: 200)

{
  "results": {
    "domain": "example.domain.com",
    "status": {
      "verified": false,
      "cname_status": "pending",
      "compliance_status": "valid"
    }
  }
}

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "8001",
      "message": "bounce domain does not exist",
      "description": "Resource not found: example.domain.com"
    }
  ]
}

Delete a Bounce Domain

DELETE/api/v1/bounce-domains/{domain}
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Delete an existing bounce domain.

Examples

Request

DELETE /api/v1/bounce-domains/example.domain.com

Response (HTTP status code: 204)

Empty response body

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "8001",
      "message": "bounce domain does not exist",
      "description": "Resource not found: example.domain.com"
    }
  ]
}

Verify

Verify a Bounce Domain

POST/api/v1/bounce-domains/{domain}/verify
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Initiate a check against the CNAME DNS record for the specified bounce domain. The domain’s status object is returned on success.

Examples

Request

POST /api/v1/bounce-domains/example.domain.com/verify

Response (HTTP status code: 200)

Response Headers
  • Content-Type: application/json; charset=utf-8
{
  "results": {
    "verified": true,
    "cname_status": "valid",
    "compliance_status": "valid"
  }
}

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "1600",
      "message": "resource not found",
      "description": "Resource not found: example.domain.com"
    }
  ]
}