After checkout, your application has an order and a recipient who needs a receipt. It uses an email API to submit the message. It records the response against the order.
Submission is only the first step. Your application also needs a way to retry a request. It needs to learn what happened to the message after submission.
How does an application event become an email?
Your application turns a completed transaction or an account request into a sending operation. The email service handles delivery after submission.
For a receipt, that sequence is:
- Your application confirms the order is ready for a receipt.
- It selects the recipient and supplies the order details as content or template values.
- It submits the send and saves the returned message ID against the order.
- It updates the sending record when delivery events arrive.
An email API can support both transactional and marketing messages. Using an API does not make promotional content transactional or remove CAN-SPAM obligations.
What does a successful response mean?
A successful submission response records what the service accepted. It is separate from the receiving mail server's later decision.
HTTP's 202 status means a request was accepted for processing. Processing has not finished, so that response cannot establish delivery.
The exact response depends on the API. Bird's send endpoint, for example, returns a queued message with an id. Keep that ID alongside the order or account event so later results can be matched to the original request.
If validation fails, Bird returns 422 with an error explaining why the request was rejected.
How do retries avoid duplicate messages?
An idempotency key identifies one logical sending operation across retries. An API that supports it can recognize a repeated request instead of creating another send.
For example, a receipt for order 8472 can use the key receipt/order-8472. Retry the same request with that key if the connection drops before you receive the response.
A fresh key identifies a different operation. Your application therefore needs to preserve the original key across its own retries and restarts.
Idempotency has a retention window defined by the provider. Once that window expires, the same key may be processed as a new request.
How do webhooks report delivery?
A webhook sends an event to your application when the message's state changes. It lets your application update its records after the initial API response.
Bird's email events distinguish these outcomes:
| Event | What it establishes |
|---|---|
email.delivered | The receiving mail server accepted responsibility for the message |
email.deferred | A temporary delivery failure will be retried |
email.bounced | The receiving server refused delivery |
email.rejected | The message did not reach a delivery attempt |
Server acceptance does not establish inbox placement or reading. A receiving server can also report a later bounce after accepting the message.
Your webhook handler must verify the sender's signature and handle duplicate deliveries. Bird's webhook contract requires deduplication using webhook-id.
What do templates change?
A stored template separates reusable message content from the values supplied for each send. Your application can supply an order number and customer name without assembling the complete email body.
With Bird's templates, a send names a published template and supplies its parameters. The template provides the subject and body.
A template does not decide when an order is complete or whether a password reset is authorized. Those decisions remain in your application.
How is it different from SMTP relay or a marketing platform?
An HTTP API and an SMTP relay are different submission interfaces. A marketing platform also manages campaign work, such as selecting an audience and scheduling a send.
| Interface or product | What your application supplies |
|---|---|
| Email API | A structured HTTP request containing recipients and content or a template |
| SMTP relay | An SMTP conversation submitting recipients and a formatted email message |
| Marketing platform | Campaign content, audience selection and sending instructions |
SMTP defines the exchange for submitting a message and its recipients. It can carry transactional or marketing mail.
Bird's SMTP relay and HTTP API use the same delivery product, including events and suppression handling. Choosing SMTP does not remove those capabilities.
How do you send transactional email through Bird?
You call POST /v1/email/messages with a verified sender, recipients and inline content or a published template. Set category: "transactional" for operational mail. The response is 202 Accepted with a message ID; delivery proceeds asynchronously.
Use an Idempotency-Key for each logical send. Bird keeps a completed response for three hours. A retry after that window can create another message, so keep your own record of completed business events.
Subscribe to email events and match email_id and recipient_id to your records. A message with multiple recipients has separate outcomes for each recipient.
For provider selection, the transactional email service checklist covers the delivery and operational capabilities to compare.