Add a receiving domain
Records a receiving subdomain and creates its SES identity in the receiving region.
It is not receiving mail yet, and the status: pending_dns in the
response is the whole reason. SendOps holds no DNS credentials and
writes no DNS anywhere, so publishing the records in records is yours
to do. A caller that treats this 201 as "inbound is live" will report
success and then wonder where the mail went. Call
POST /v1/inbound/domains/{domain}/verify once the records are up.
The domain must be equal to, or a subdomain of, a domain your org
already holds in SendOps — otherwise 422 receiving_domain_not_owned.
Some stack on the AWS account must carry the inbound module, or 422
inbound_not_deployed. A domain already recorded on the account is 409.
The SES identity goes in the RECEIVING region, which is the region of
the stack carrying the inbound module and need not be your sending
region: only 22 AWS regions receive mail at all, so cross_region: true
is ordinary rather than a misconfiguration.
Request body
Content type: application/json
domain string required The receiving subdomain, e.g. in.acme.com. Must be equal to, or a subdomain of, a domain your org already holds in SendOps.
Responses
Errors follow the RFC 7807 problem format — see the error reference.
domain string required id string<uuid> required status string enum required error means a CHECK could not be performed — a resolver failure, an SES call that failed — and is NOT "the record is missing", which is pending_dns. Polling continues either way, so error is never terminal.
One of: pending_dns, verified, error
last_error string optional The first thing missing or wrong, in plain words. Absent on a verified domain.
region string required The RECEIVING region — the region of the stack carrying the inbound module, and the region whose SES endpoint your MX must name.
cross_region boolean required True when the receiving region differs from the account's sending region. A fact to state, never an error: only 22 AWS regions receive mail at all.
mx_verified_at string<date-time> optional identity_verified_at string<date-time> optional records array<object> required The copy-paste DNS instruction set. SendOps will never publish these for you — it holds no DNS credentials — so this list is the whole of what turns pending_dns into verified.
Each entry in records:
type string enum required One of: MX, CNAME
name string required value string required verified boolean required webhook object | null required Null when no webhook is configured.
Fields of webhook:
url string<uri> required allow_patterns array<string> required Local-part globs — support, ticket-*. EMPTY MEANS EVERY RECIPIENT AT THE DOMAIN IS DELIVERED, which is the opposite of how an empty list usually reads and is the most consequential field on this shape. A recipient that matches nothing in a non-empty list is recorded as no_route.
spam_posture string enum required tag delivers a message SES marked as spam, with the verdict stated in the payload; drop records the outcome and delivers nothing.
One of: tag, drop
virus_posture string enum required One of: tag, drop
status string enum required pending means the routing has not been re-published yet, which normally closes within seconds. invalid means the URL failed re-validation at publish time — most often a host that stopped resolving, or one that now resolves to a private address — so the domain was left out of the routing entirely; error says which.
One of: unset, pending, published, invalid
error string optional published_at string<date-time> optional created_at string<date-time> required code: invalid_scope), or it is bound to the test environment and this operation is irreversible (code: test_environment_forbidden). Branch on code: the first is fixed by granting the scope, the second only by using a live credential. See the "Live and test credentials" section of the API description. application/problem+json code is conflict.
application/problem+json validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json