Inbound Domains

Specifying an inbound domain enables you to customize the address to which inbound messages are sent. Inbound domains are used in conjunction with Relay Webhooks. You can have multiple inbound domains but each domain must be globally unique.

Before you can use your inbound domain (e.g. inbounddomain.test.com), you will need to add MX records to your DNS settings. The following DNS settings are for all plans except SparkPost Enterprise:

Name Type Data Priority
inbounddomain.test.com MX rx1.sparkpostmail.com 10
inbounddomain.test.com MX rx2.sparkpostmail.com 10
inbounddomain.test.com MX rx3.sparkpostmail.com 10
SparkPost Enterprise customers, you will need to use MX records similar to your existing domains. In many cases the MX records for existing domains point at inbound.. The following DNS settings assume that your existing domains point at inbound.. Please check with your TAM if you are unsure of the setting in your own environment.
Name Type Data Priority
inbounddomain.test.com MX inbound.<main-bounce-domain> 10

Inbound Domains Attributes

Field Type Description Required Notes
domain string Domain (or subdomain) name for which SparkPost will receive inbound emails yes Your DNS provider’s MX record for this domain must point back to SparkPost. (Example: inbounddomain.test.com)

Using Postman

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

Run in Postman

Create and List

Create an Inbound Domain

POST/api/v1/inbound-domains

Create an inbound domain by providing an inbound domains object as the POST request body.

Examples

Request

POST /api/v1/inbound-domains

{
  "domain": "inbounddomain.test.com"
}

Response (HTTP status code: 200)

Empty response body

Response (HTTP status code: 400)

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

Response (HTTP status code: 401)

{
  "errors": [
    {
      "message": "Unauthorized Tenant",
      "code": "1303"
    }
  ]
}

Response (HTTP status code: 409)

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

Request: Missing Domain

POST /api/v1/inbound-domains

{}

Response (HTTP status code: 422)

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

Request: Invalid Domain

POST /api/v1/inbound-domains

{
  "domain": "inbounddomain"
}

Response (HTTP status code: 422)

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

List all Inbound Domains

GET/api/v1/inbound-domains

List all your inbound domains.

Examples

Request

GET /api/v1/inbound-domains

Response (HTTP status code: 200)

{
  "results": [
    {
      "domain": "inbounddomain.test.com"
    },
    {
      "domain": "inbounddomain2.test.com"
    }
  ]
}

Response (HTTP status code: 401)

{
  "errors": [
    {
      "message": "Unauthorized Tenant",
      "code": "1303"
    }
  ]
}

Retrieve and Delete

Retrieve an Inbound Domain

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

Domain name

Example: inbounddomain.test.com

Retrieve an inbound domain by specifying its domain name in the URI path.

Examples

Request

GET /api/v1/inbound-domains/inbounddomain.test.com

Response (HTTP status code: 200)

{
  "results": {
    "domain": "inbounddomain.test.com"
  }
}

Response (HTTP status code: 401)

{
  "errors": [
    {
      "message": "Unauthorized Tenant",
      "code": "1303"
    }
  ]
}

Response (HTTP status code: 404)

{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600"
    }
  ]
}

Delete an Inbound Domain

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

Domain name

Example: inbounddomain.test.com

Delete an inbound domain by specifying its domain name in the URI path.

Examples

Request

DELETE /api/v1/inbound-domains/inbounddomain.test.com

Response (HTTP status code: 200)

Empty response body

Response (HTTP status code: 401)

{
  "errors": [
    {
      "message": "Unauthorized Tenant",
      "code": "1303"
    }
  ]
}

Response (HTTP status code: 404)

{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600"
    }
  ]
}

Response (HTTP status code: 409)

{
  "errors": [
    {
      "message": "resource conflict",
      "description": "Domain currently being used in a relay-webhook. Please delete the relay-webhook first.",
      "code": "1602"
    }
  ]
}