Your application sends structured data to an HTTP endpoint and receives a response with the message result or an error. That request and response are the working surface of an email API.
What does an email API handle?
A sending endpoint accepts recipients, a subject, and text or HTML content. It can also accept headers, tags, templates, and attachments when the provider supports them.
An event endpoint or webhook reports what happened after acceptance. Common events include delivery, bounce, complaint, open, and click. A receiving API turns inbound mail into structured messages for your application instead of making you poll a mailbox.
How is an email API different from SMTP?
SMTP requires your application to open a connection, authenticate, send commands, and read reply codes. An email API uses HTTP requests instead, so a client library can handle connection reuse, JSON encoding, retries, and response parsing.
Choose an API when your application already uses HTTP, needs structured events, or runs where opening SMTP connections is awkward. Choose an SMTP relay when an existing mail library or mail server already speaks SMTP. The two paths can deliver the same message.
| Task | Sending API | SMTP relay | Mailbox API |
|---|---|---|---|
| Send a message | Yes | Yes | Reply or compose |
| Receive parsed mail | Some providers | No | Yes |
| Read conversation history | Some providers | No | Yes |
| Observe delivery | Events or webhooks | Reply codes plus events | Message status and events |
Products use the term email API for different capability sets. Check the provider's schema before assuming one API covers every row.
What should an API request include?
Send the fields your provider requires. Record the returned message identifier. Keep your own idempotency key when a retry must not create a duplicate send. Validate recipients before sending. Keep secrets on your server.
An illustrative transactional request has from, to, subject, text, category: transactional, and an idempotency key held on the server. Use a verified sending domain before sending it.
The HTTP response means the service accepted the request. Delivery, bounce, and complaint events arrive later, so an accepted response does not establish inbox placement.
Use webhooks for later events rather than treating an accepted request as proof that a message reached an inbox. Delivery and complaint events describe what happened after acceptance.
How do I send with Bird?
You call Bird's createEmailMessage API with your workspace API key, sender, recipients, content, and optional metadata. The email sending guide shows the request and response fields.
For replies and inbound mail, create a mailbox and consume its message and delivery events. The mailboxes guide covers those endpoints and webhook names.
In short
- An email API exposes sending and message events through HTTP.
- The response confirms API acceptance, not inbox placement.
- Idempotency keys make safe retries possible.
- Bird provides sending and mailbox APIs with guides for each path.