Provision domain

POST 
/domains

Provision a single domain to use MailChannels Inbound.

Request

Query Parameters

associate-key boolean

If present and set to true, the domain will be associated with the api-key that created it. This means that this api-key must be used for inbound-api actions involving this domain (for example adding safe/block list entries, etc).

overwrite boolean

If present and set to true, the settings (domain settings, downstream addresses, aliases and admins) for the domain will be overwritten with the ones in the request if the domain already exists, unless a section is not included in the request or there is problem updating a setting in which case the previous settings are carried forward.

application/json

Body

required

domain hostnamerequired

The domain name.

subscriptionHandle stringrequired

The subscription 'handle' that identifies the subscription that this domain should be provisioned against. Subscription handles can be retrieved from the /subscriptions endpoint.

settings

The abuse policy settings for the domain. These settings determine how spam messages are handled.

abusePolicy stringnullable

The abuse policy

Possible values: non-empty, [block, flag, quarantine]

abusePolicyOverride booleannullable

If true, this abuse policy overrides the recipient abuse policy.

spamHeaderName stringnullable

The spam header name to use if the abuse policy is set to 'flag'.

Possible values: non-empty

spamHeaderValue stringnullable

The spam header value to use if the abuse policy is set to 'flag'.

Possible values: non-empty

admins string[]

A list of email addresses that are the domain admins for the domain.

downstreamAddresses

object[]

The locations of mail servers to which messages will be delivered after filtering.

Array [

priority integerrequired

The priority of the dowsntream address. Only addresses with the highest priority (the lowest numerical value) are selected.

weight integerrequired

Downstream addresses are selected in proportion to their weights. For example, if there are two downstream addresses, A with weight 40, and B with weight 10, then A is selected 80% of the time and B is selected 20% of the time.

port integerrequired

TCP port on which the downstream mail server is listening.

target stringrequired

The canonical hostname of the host providing the service, ending in a dot.

Possible values: <= 255 characters

]

aliases string[]

A list of aliases for the domain. Mail is accepted for these domains and routed to the downstreamAddresses defined for the domain.

Responses

200

The domain was already provisioned to use MailChannels Inbound.

application/json

Schema

Schema

domain hostnamerequired

The domain name.

subscriptionHandle stringrequired

The subscription 'handle' that identifies the subscription that this domain should be provisioned against. Subscription handles can be retrieved from the /subscriptions endpoint.

settings

The abuse policy settings for the domain. These settings determine how spam messages are handled.

abusePolicy stringnullable

The abuse policy

Possible values: non-empty, [block, flag, quarantine]

abusePolicyOverride booleannullable

If true, this abuse policy overrides the recipient abuse policy.

spamHeaderName stringnullable

The spam header name to use if the abuse policy is set to 'flag'.

Possible values: non-empty

spamHeaderValue stringnullable

The spam header value to use if the abuse policy is set to 'flag'.

Possible values: non-empty

admins string[]

A list of email addresses that are the domain admins for the domain.

downstreamAddresses

object[]

The locations of mail servers to which messages will be delivered after filtering.

Array [

priority integerrequired

The priority of the dowsntream address. Only addresses with the highest priority (the lowest numerical value) are selected.

weight integerrequired

Downstream addresses are selected in proportion to their weights. For example, if there are two downstream addresses, A with weight 40, and B with weight 10, then A is selected 80% of the time and B is selected 20% of the time.

port integerrequired

TCP port on which the downstream mail server is listening.

target stringrequired

The canonical hostname of the host providing the service, ending in a dot.

Possible values: <= 255 characters

]

aliases string[]

A list of aliases for the domain. Mail is accepted for these domains and routed to the downstreamAddresses defined for the domain.

Example (from schema)

{
  "domain": "example.com",
  "subscriptionHandle": "string",
  "settings": {
    "abusePolicy": "block",
    "abusePolicyOverride": true,
    "spamHeaderName": "string",
    "spamHeaderValue": "string"
  },
  "admins": [
    "string"
  ],
  "downstreamAddresses": [
    {
      "priority": 0,
      "weight": 0,
      "port": 0,
      "target": "string"
    }
  ],
  "aliases": [
    "string"
  ]
}

201

The domain has been successfully provisioned to use MailChannels Inbound.

application/json

Schema

Schema

domain hostnamerequired

The domain name.

subscriptionHandle stringrequired

The subscription 'handle' that identifies the subscription that this domain should be provisioned against. Subscription handles can be retrieved from the /subscriptions endpoint.

settings

The abuse policy settings for the domain. These settings determine how spam messages are handled.

abusePolicy stringnullable

The abuse policy

Possible values: non-empty, [block, flag, quarantine]

abusePolicyOverride booleannullable

If true, this abuse policy overrides the recipient abuse policy.

spamHeaderName stringnullable

The spam header name to use if the abuse policy is set to 'flag'.

Possible values: non-empty

spamHeaderValue stringnullable

The spam header value to use if the abuse policy is set to 'flag'.

Possible values: non-empty

admins string[]

A list of email addresses that are the domain admins for the domain.

downstreamAddresses

object[]

The locations of mail servers to which messages will be delivered after filtering.

Array [

priority integerrequired

The priority of the dowsntream address. Only addresses with the highest priority (the lowest numerical value) are selected.

weight integerrequired

Downstream addresses are selected in proportion to their weights. For example, if there are two downstream addresses, A with weight 40, and B with weight 10, then A is selected 80% of the time and B is selected 20% of the time.

port integerrequired

TCP port on which the downstream mail server is listening.

target stringrequired

The canonical hostname of the host providing the service, ending in a dot.

Possible values: <= 255 characters

]

aliases string[]

A list of aliases for the domain. Mail is accepted for these domains and routed to the downstreamAddresses defined for the domain.

Example (from schema)

{
  "domain": "example.com",
  "subscriptionHandle": "string",
  "settings": {
    "abusePolicy": "block",
    "abusePolicyOverride": true,
    "spamHeaderName": "string",
    "spamHeaderValue": "string"
  },
  "admins": [
    "string"
  ],
  "downstreamAddresses": [
    {
      "priority": 0,
      "weight": 0,
      "port": 0,
      "target": "string"
    }
  ],
  "aliases": [
    "string"
  ]
}

400

Bad Request, returned in the case that an error occurs while converting an A-label domain to a U-label domain name.

application/json

Schema

Schema

code integer
message string
errors string[]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    "string"
  ]
}

403

A 403 response can be returned in two cases:

1. The limit on associated domains is reached. Contact sales@mailchannels.com to increase your limit.

2. You are attempting to associate a domain with a subscription that is not your own.

application/json

Schema

Schema

code integer
message string
errors string[]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    "string"
  ]
}

409

The domain is already provisioned, and is associated with a different customer.

application/json

Schema

Schema

code integer
message string
errors string[]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    "string"
  ]
}

500

Internal Server Error

application/json

Schema

Schema

code integer
message string
errors string[]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    "string"
  ]
}

Loading...