Bulk provision domains

POST 
/domains/batch

Provision up to 1000 domains to use MailChannels Inbound.

Request

Query Parameters

subscriptionHandle stringrequired

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

associate-key boolean

If present and set to true, the domains will be associated with the api-key in the header. This means that this api-key must be used for inbound-api actions involving these domains (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 any existing domains will be overwritten with the ones in the request, 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

domains

object[]

Possible values: <= 1000

Array [

domain hostnamerequired

The domain name to be provisioned.

downstreamAddress

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

]

settings

The abuse policy settings for the domains. 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

aliases string[]

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

admins string[]

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

]

Responses

200

The request was processed successfully. This does not necessarily mean all the domains in the request were successfully provisioned. See the CommentedDomain definition for more information.

application/json

Schema

Schema

successes

undefined[]

Array [

domain

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.

code integerrequired

• 201: This domain was successfully created.
• 400: A 400 response is typically returned in the following case(s):

1. The domain name was an A label that did not meet the specifications in RFC 3490

• 409: The domain is already provisioned, and is associated with a different customer.
• 500: There was an error provisioning the domain.

Possible values: [201, 400, 409, 500]

comment string

More information about the result of domain provisioning.

]

errors

undefined[]

Array [

domain

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.

code integerrequired

• 201: This domain was successfully created.
• 400: A 400 response is typically returned in the following case(s):

1. The domain name was an A label that did not meet the specifications in RFC 3490

• 409: The domain is already provisioned, and is associated with a different customer.
• 500: There was an error provisioning the domain.

Possible values: [201, 400, 409, 500]

comment string

More information about the result of domain provisioning.

]

Example (from schema)

{
  "successes": [
    {
      "domain": {
        "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"
        ]
      },
      "code": 201,
      "comment": "string"
    }
  ],
  "errors": [
    {
      "domain": {
        "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"
        ]
      },
      "code": 201,
      "comment": "string"
    }
  ]
}

400

Bad Request, returned in the case that a domain name fails RFC 5891 validation

application/json

Schema

Schema

code integer
message string
errors string[]

Example (from schema)

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

403

Creating the domains will exceed the number of domains allowed with the specified subscription, or you are attempting to use a subscription that is not your own. None of the domains have been provisioned. Contact sales@mailchannels.com to increase your limit

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