Receiving email

How to receive email with Inboundr: get each message by webhook in real time, or read stored inboxes on demand over REST or MCP.

Once a domain is verified, it accepts mail on every address. There are two ways to get that mail into your code.

Option A: webhooks, in real time#

Use this when you want to react as soon as mail arrives.

Create an endpoint

bash

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 secret in the response. You'll use it to verify signatures.

Route mail to it

Route a single address:

bash

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

Or send all of the domain's mail to it with the catch-all:

bash

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"] }'

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#

Use this for agents that read mail when they act, without running a server. Create a store-only address (one with no endpoint), or rely on the domain with no catch-all set. Either way, mail is parsed and stored for you to read.

bash

# 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, with its bodies and attachment metadata, by ID:

bash

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

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

Choosing an approach#

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

You can use both. Every inbox keeps its mail readable over REST and MCP, even when it also delivers to a webhook.