How Inboundr works

The five objects in Inboundr's model, and the path an email takes from the sender to your code.

Inboundr's object model is small. Once you know these five objects, the rest of the docs build on them.

Object	ID prefix	What it is
Domain	`dom_`	A domain you own and have verified. Everything else belongs to one.
Address	None	A specific mailbox on a domain, such as `agent@yourdomain.com`.
Endpoint	`ep_`	A webhook URL that mail can be delivered to.
Email	`em_`	One parsed inbound message.
Thread	`thr_`	A group of emails that make up one conversation.

What happens to an incoming email#

When someone emails an address on your domain, Inboundr handles it in four stages:

Routing: where does it go?
Inboundr looks up the recipient in order. A route on that exact address is used first. If there isn't one, the domain's catch-all endpoint is used. If there's no catch-all either, the message is stored without being delivered anywhere. See Addresses & routing.
Parsing: MIME to JSON
The raw message becomes an email: sender and recipients, subject, text and HTML bodies, attachment metadata, and SPF, DKIM and spam verdicts.
Threading: which conversation?
Inboundr reads the Message-ID, In-Reply-To and References headers and puts the email on a thread, either the conversation it belongs to or a new one.
Delivery: to your code
If the route points at an endpoint, Inboundr sends a signed webhook. In every case the email is stored and can be read through the REST API and MCP.

Two ways to receive mail#

You can choose per address, or use both at once.

Push: webhooks

Route an address, or the catch-all, to an endpoint. Inboundr POSTs each message to your URL as it arrives. A good fit when you run a server.

Pull: store-only

Leave an address without an endpoint. Mail is parsed and stored, and you read it when you're ready with list_emails or GET /v1/emails. A good fit for agents and scripts.

Next: Domains