Domains

A domain is the starting point for everything in Inboundr. Once you register and verify a domain you control, every address on it can receive mail that your code reads.

Setting up a domain#

1. Register

   Add the domain in the console or with POST /v1/domains. Inboundr creates an email identity for it and returns the DNS records to publish.

2. Publish the DNS records

   At your DNS host, add the MX record, which routes the domain's mail to Inboundr, and the DKIM CNAME records, which prove you own the domain.

3. Verify

   Inboundr checks DNS again every few minutes. Once it sees the DKIM records, the domain's status changes to verified and mail starts flowing. Fetching a pending domain through the API also triggers an immediate check.

Verification status#

Catch-all routing#

A verified domain accepts mail on any address by default, so you don't have to create each address first. To deliver mail for addresses that have no route of their own, set the domain's catch-all to a webhook endpoint:

curl -X PATCH https://inboundr.net/api/v1/domains/dom_123 \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "catchAllEndpointIds": ["ep_123"] }'

The single-endpoint form, "catchAllEndpointId": "ep_123", also works. To turn the catch-all off, pass [] (or "catchAllEndpointId": null). With no catch-all, mail to an unrouted address is still parsed and stored, so you can read it over the API and MCP, but no webhook is sent.

An address route for a specific address always takes precedence over the catch-all.

Deleting a domain#

Deleting a domain removes its email identity and stops processing its mail straight away. Emails already stored are kept, but nothing new is accepted.