Skip to main content

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.

Body

required

    domains

    object[]

    Possible values: <= 1000

  • Array [

  • domainhostnamerequired

    The domain name to be provisioned.

    downstreamAddress

    object[]

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

  • Array [

  • priorityintegerrequired

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

    weightintegerrequired

    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.

    portintegerrequired

    TCP port on which the downstream mail server is listening.

    targetstringrequired

    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.

    abusePolicystringnullable

    The abuse policy

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

    abusePolicyOverridebooleannullable

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

    spamHeaderNamestringnullable

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

    Possible values: non-empty

    spamHeaderValuestringnullable

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

    Possible values: non-empty

    aliasesstring[]

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

    adminsstring[]

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

  • ]

Responses

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.

Schema

    successes

    undefined[]

  • Array [

  • domain

    required

    domainhostnamerequired

    The domain name.

    subscriptionHandlestringrequired

    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.

    abusePolicystringnullable

    The abuse policy

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

    abusePolicyOverridebooleannullable

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

    spamHeaderNamestringnullable

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

    Possible values: non-empty

    spamHeaderValuestringnullable

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

    Possible values: non-empty

    adminsstring[]

    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 [

  • priorityintegerrequired

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

    weightintegerrequired

    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.

    portintegerrequired

    TCP port on which the downstream mail server is listening.

    targetstringrequired

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

    Possible values: <= 255 characters

  • ]

  • aliasesstring[]

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

    codeintegerrequired
    • 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]

    commentstring

    More information about the result of domain provisioning.

  • ]

  • errors

    undefined[]

  • Array [

  • domain

    required

    domainhostnamerequired

    The domain name.

    subscriptionHandlestringrequired

    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.

    abusePolicystringnullable

    The abuse policy

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

    abusePolicyOverridebooleannullable

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

    spamHeaderNamestringnullable

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

    Possible values: non-empty

    spamHeaderValuestringnullable

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

    Possible values: non-empty

    adminsstring[]

    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 [

  • priorityintegerrequired

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

    weightintegerrequired

    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.

    portintegerrequired

    TCP port on which the downstream mail server is listening.

    targetstringrequired

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

    Possible values: <= 255 characters

  • ]

  • aliasesstring[]

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

    codeintegerrequired
    • 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]

    commentstring

    More information about the result of domain provisioning.

  • ]