Subdomain and addresses

Every tenant that receives real mail claims a handle on the inbound domain and creates addresses under it. A handle acme answers to three forms of the same address:

Form	Example	When
Apex, dotted	`acme.orders@mximp.com`	The everyday form; what `create_address` returns.
Apex, plus	`acme+orders@mximp.com`	For senders who prefer plus-addressing.
Subdomain	`orders@acme.mximp.com`	Tenants given a dedicated subdomain; a paid option, since the mail provider enables subdomains one at a time.

Sandboxes have no handle; they ingest by upload.

Claiming a handle

claim_subdomain with a name. Rules:

Lowercase letters, digits, single hyphens; 8 to 40 characters; at least one letter; unique across the platform.
Reserved words (support, admin, billing, mail, api, and so on) are refused when they stand alone or carry only a numeric or hyphenated suffix: support, support2, support-team. A longer word containing one is fine: supportcompany.
Brand names are refused wherever they appear, to prevent impersonation.
Mail-infrastructure prefixes (mx, smtp, dkim…) are refused with any digits.

A refusal names the rule. If the name is genuinely yours, call again with request_exception: true and a reason. A person reviews it; there is no automatic approval. If approved, the subdomain appears on your tenant and get_subdomain shows it. An exception is bound to your tenant and that exact name; the format rules apply even then.

Addresses

create_address makes an inbound address under the handle:

Named: acme.orders@mximp.com. You choose the local part.
Relationship: acme.r-k7m2x9pq4t@mximp.com, opaque and unguessable, bound to a relationship_ref of yours such as a vendor id. Mail to it is either that relationship or a leak; both are signals. Give one to each counterparty.

Pass bucket to create_address to make the address a bucket's own: the bucket's rule gains {"address": "orders@"} as an alternative, so mail to it lands there without further rule work, and list_buckets shows the full address beside the bucket with its activity (messages, auto-applied, held, last received over days). That is the address a person hands to a sender; the app lists them with a copy button.

Any address can be disabled (set_address_enabled), which is the first response when one leaks, and can carry a daily cap. set_catch_all accepts mail to any local part under the handle; it is off by default because a catch-all receives everything anyone sends.

Mail to an address that does not exist, or is disabled, is refused at the door and counted, so abuse is visible to the operator without the message ever being stored.

What rules see

The receiving address is the envelope recipient, recorded in its canonical dotted form acme.orders@mximp.com whichever form the sender used. A rule like {"address": "orders@"} matches the part after the handle, so it means the same thing in all three forms. Per-relationship addresses match the same way. The sender's identity comes from SPF, DKIM and DMARC results, never from the message body.

This page as Markdown.