Receiving email

Once a domain is verified, it accepts mail on every address. How you consume that mail is up to you.

Option A — Webhooks (real time)

Best when you want to react the moment mail arrives.

Create an endpoint

curl https://inboundr.net/api/v1/endpoints \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Inbound handler", "url": "https://api.example.com/hooks/inbound" }'

Save the returned secret — you’ll use it to verify signatures.

Route mail to it

Route a single address:

curl https://inboundr.net/api/v1/addresses \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domainId": "dom_123", "localPart": "support", "endpointId": "ep_123" }'

…or catch everything on the domain:

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

Handle the delivery

Inboundr POSTs a signed email.received payload to your URL. Verify the signature, then process the message. See the payload structure and signature verification.

Option B — Read on demand (store-only)

Best for agents that read when they act, rather than running a server. Create a store-only address (no endpointId) or just rely on catch-all with no endpoint set — mail is parsed and stored either way.

# Newest inbound messages
curl "https://inboundr.net/api/v1/emails?direction=inbound&limit=20" \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"

# Everything sent to one address
curl "https://inboundr.net/api/v1/emails?to=support@yourdomain.com" \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"

Fetch a single message in full (bodies + attachment metadata) by id:

curl https://inboundr.net/api/v1/emails/em_abc123 \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"

Agents can skip HTTP entirely and use the MCP tools list_emails, get_email, and get_thread to read the same data.

Choosing an approach

	Webhooks	Read on demand
Latency	Real time	When you poll / call
Needs a public URL	Yes	No
Best for	Servers, automations	Agents, scripts, batch

You can use both — a store-only inbox is always readable even when it also delivers to a webhook.

Start here

How Inboundr works

Recipes

Webhooks

Agents & MCP

Account

Option A — Webhooks (real time)

Option B — Read on demand (store-only)

Choosing an approach

​Option A — Webhooks (real time)

​Option B — Read on demand (store-only)

​Choosing an approach

Option A — Webhooks (real time)

Option B — Read on demand (store-only)

Choosing an approach