Loading article…
Loading article…
Email API vs inbox API: What are you actually building?
Learn the difference between a sending API, inbound email processing, and an inbox API, then choose the right email architecture for your product.
Learn the difference between a sending API, inbound email processing, and an inbox API, then choose the right email architecture for your product.
Loading article…
An email API sends or receives email for software. An inbox API gives software access to a stored mailbox and its conversations.
The terms overlap, and "inbox API" is not a formal industry standard. The useful question is simpler: does your application need to move messages, or does it need to own and revisit a mailbox?
Choose a sending API for receipts, login links, alerts, and other messages triggered by your product. Choose an inbox API when your application or agent must receive mail, keep threads, read old messages, and reply from a durable address.
"Email API" can describe three different products.
A sending API accepts a request from your application and delivers an email. Your code supplies the sender, recipients, subject, and body.
This is the common choice for:
The provider may track delivery, bounces, and complaints. It may also offer templates, analytics, and suppression lists.
A sending API does not necessarily provide a mailbox. A recipient may reply, but your application needs somewhere to receive and process that reply.
An inbound parser accepts email for an address or domain, turns the message into structured data, and sends it to your webhook.
Postmark, for example, describes its inbound service as accepting and parsing a message, then posting it to a configured URL as JSON. Resend can notify an application with an email.received webhook, after which the application can retrieve the message and its attachments.
Both products now cover more than one category. See Startup Mail vs Postmark and Startup Mail vs Resend for their current receiving and storage models.
This removes much of the MIME parsing work. It still leaves important decisions to your application:
An inbound webhook is an event. It is not, by itself, a complete inbox.
For a closer look at this boundary, read inbound email webhook vs persistent mailbox.
An inbox API treats the mailbox as a lasting resource.
It stores incoming and outgoing messages, groups replies into threads, and lets an authorized client return later to read the current state. It may also provide a human inbox, webhooks, forwarding, search, attachments, and mailbox permissions.
This is the model Startup Mail uses. The mailbox is the source of truth. A webhook tells your application that something changed, while the API returns the current conversation.
| Question | Sending API | Inbound parser | Inbox API |
|---|---|---|---|
| Can it send email? | Usually | Sometimes | Usually |
| Can it receive email? | Not always | Yes | Yes |
| Does it store a mailbox? | Usually no | Varies | Yes |
| Does it preserve threads? | Delivery history only or provider-specific | Your application may need to build this | Yes |
| Can a human read the same mailbox? | Usually no | Not without another interface | Often |
| Does software fetch old conversations? | Usually limited to delivery records | Varies | Yes |
| Does it notify code about new mail? | Delivery webhooks | Inbound webhook | Inbound webhook plus mailbox API |
| Main job | Deliver a message | Turn incoming email into data | Maintain an email identity and its conversations |
Provider names alone do not settle this table. Products change, and some now span more than one category. Read the current documentation and test the exact message lifecycle you need.
Suppose a new message reaches your application while its webhook endpoint is unavailable.
With a basic parser, the provider may retry delivery. Your application is still responsible for storing the message once it arrives. If processing succeeds but the acknowledgement fails, the event may arrive again. You need a stable event ID and idempotent processing so the second delivery does not create a duplicate action.
With an inbox API, the webhook can remain a notification. Your worker verifies the event, records its delivery ID, and fetches the thread from the API. If the webhook repeats, the mailbox still has one conversation.
This does not remove the need for careful code. It gives that code a durable object to read.
Startup Mail signs webhook requests and retries failed deliveries. Its documentation recommends acknowledging the webhook quickly, deduplicating by delivery ID, and fetching the current thread after the event.
A message is one email. A thread is the conversation that links messages and replies.
Threads become important when:
A sending API can put reply headers on an outgoing message. An inbound parser can expose the headers on the response. Your application may still need to match them, store the messages, handle missing or malformed headers, and present the conversation.
An inbox API should make the thread a first-class resource. In Startup Mail, an application can list threads, retrieve every message in a thread, and reply to a specific message so the outgoing email stays in the conversation.
Email contains private and often sensitive data. A useful API must answer more than "does this key work?"
Ask:
Startup Mail separates human workspace roles from API resource boundaries. A key can cover the organization, one tenant, or one mailbox. Capabilities then control what it can do inside that boundary. An agent can start with a mailbox-scoped read-only key and receive draft or sending permission only when the workflow needs it.
The Gmail API uses a different model. Applications request access to a user's Gmail account through Google authorization. It is a strong fit when the mailbox already belongs to a Gmail user. Startup Mail is a more direct fit when the application needs a mailbox created for the workload itself.
Choose a sending API if:
Choose an inbound parser if:
Choose an inbox API if:
Yes. A split system is often sensible.
A product can use a specialist sending API for large volumes of application notifications and use an inbox API for support@, vendors@, or an agent address that receives replies.
The main risk is fragmentation. Decide which system owns each address, message type, and reply path. Do not let two systems believe they are the source of truth for one mailbox.
A simple boundary might be:
Startup Mail is built for the second group and for requested transactional mail. It is not a marketing campaign service.
The right API follows from those answers. Start with the message lifecycle, not the vendor list.
If your decision is mainly about employee mail versus product notifications, continue with transactional email service vs business email hosting.