An inbound email API receives mail sent to an address or domain you own, parses it, and delivers it to your application as a structured HTTP POST. Instead of running a mail server and polling a mailbox over IMAP, you point your domain's MX records at the provider, and every incoming message arrives at your endpoint with the headers, body, and attachments already parsed into JSON.
How does inbound email work?
The routing starts with DNS. You set the MX records for a domain or subdomain (say reply.yourapp.com) to point at the inbound provider's mail servers. When someone sends a message to any address at that domain, it lands on the provider's infrastructure rather than yours. The provider accepts the message, parses it, and makes a POST request to a URL you registered, carrying the parsed contents.
A parsed payload typically includes the sender and recipient, the subject, the plain-text and HTML bodies, the full header set, and any attachments (often base64-encoded or referenced by a URL). Your app reads that JSON and acts on it, with no SMTP or IMAP code to maintain. The delivery mechanism is a webhook, so the same rules apply: respond with a quick 2xx, then process the message asynchronously.
What is it used for?
Inbound email turns received messages into application events. Common patterns include:
- Reply handling. Send a notification from
notifications@yourapp.com, and when a user replies, the reply arrives as a POST so you can thread it back into a conversation. - Support ticketing. Mail to
support@yourapp.combecomes a new ticket, with the sender and body mapped straight into your help desk. - Parse to database. Forwarded receipts or structured emails get parsed and written to a table, no manual entry.
- Email to action. A message to a special address triggers a workflow: create a record, kick off a job, post to a channel.
How is it different from sending mail?
Outbound and inbound are separate jobs. Outbound is your app delivering mail to recipients through SMTP or an HTTP send API. Inbound is the reverse: external senders delivering mail to your app. A complete email integration usually does both, sending notifications out and receiving the replies back, but they are configured independently and the inbound side is what depends on your MX records.
Why not poll a mailbox over IMAP instead?
You can run an IMAP poller against a real mailbox, but it carries ongoing cost. You manage credentials, you decide how often to poll (which adds latency and idle connections), you parse raw MIME yourself, and you track which messages you have already processed. An inbound API removes most of that: the provider parses the MIME, pushes each message once as clean JSON, and you react in near real time. For a comparison of the underlying protocols, see SMTP vs. IMAP.
Frequently asked questions
What DNS changes do I need?
You set the MX records for the domain or subdomain you want to receive mail on to point at your inbound provider. After propagation, mail to any address at that domain flows to the provider, which parses it and posts it to your endpoint. Using a dedicated subdomain keeps inbound routing separate from your main domain's mail.
How are attachments handled?
The parsed payload includes attachments, usually either base64-encoded inline or as URLs you fetch separately. Your handler decodes or downloads them and stores them wherever you keep files. Larger attachments are typically referenced by URL to keep the payload small.
Is inbound email the same as a webhook?
The delivery uses a webhook: the provider sends your app an HTTP POST for each message. The difference is the payload is a fully parsed email rather than a generic event. Treat it like any webhook by verifying it, responding quickly, and processing asynchronously.
To see how Bird handles both directions of email, start with the email product overview and the email events guide, which covers the event delivery model your inbound handler will build on.