# 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](/docs/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.