Give the request a way in.
Use a forwarding address or a receiving subdomain to bring the customer’s email into your application.
EmailInbound Email API: Receive & Process Email
Inbound email.
Put every reply to work.
Bring received messages, content, and attachments into your application. Start the next workflow with the details your customer has already sent.
Incoming emailAL
Alex LeeTo: studio@fieldnotes.example
A little question
about Friday.
Could we move booking FN–1042 to the afternoon? The original booking is attached.
booking.pdfApplication reads the retained attachment
Receiving eventExample · no request is madeevent: email.receivedmessage: rem_example_fn1042 Verify the event.Read the content.Start the application workflow.
Incoming emailAL
Alex LeeTo: studio@fieldnotes.example
A little question
about Friday.
Could we move booking FN–1042 to the afternoon? The original booking is attached.
booking.pdfApplication reads the retained attachment
Content available to your applicationExample · no request is madefrom alex@example.comsubject A little question about Friday.text Could we move booking FN–1042 to the afternoon? attachment name booking.pdf type application/pdf
Content available to your applicationExample · no request is madefrom alex@example.comsubject A little question about Friday.text Could we move booking FN–1042 to the afternoon? attachment name booking.pdf type application/pdf
Your application / Work itemCUSTOMER SERVICEOne request.
One request.
The details included.
- Customer
- Alex Lee
- Reference
- FN–1042
- Request
- Move the visit to the afternoon
- Context
- Original booking attached
Connecting customers.
In good company.Meet Bird’s customers ↗Customers across the Bird platform.
In good company.Meet Bird’s customers ↗Customers across the Bird platform.
See more Bird platform customers
Companies that trust Bird across their communications.
Read Bird customer storiesWHAT IT MEANS FOR YOUR CUSTOMERThey already sent the detail.
They already sent the detail.
Put it to useful work.
A reply, document, or request can be the beginning of your next application workflow. Receive the content without making your team run an inbound mail server.
Work with the content.
Read parsed text, message details, and attachments so your workflow starts with what the customer supplied.
Wake the right workflow.
Use the incoming-message event to queue work in your application, with a durable record for recovery.
READY WHEN YOU ARE
Give the next message a way in.
BUILD WITH INBOUND EMAILListen for the reply.
Listen for the reply.
Build what happens next.
A server-side acceptance handler: verifies the raw body and durably inserts each webhook-id once. Your worker processes the inbox, checks sender authentication, and owns business actions. Prepare the durable inbox table shown in the sample, then use the webhook guide for retries and recovery.
Open the implementation guide →app/api/webhooks/route.js
npm install @messagebird/sdk pgimport { BirdClient } from "@messagebird/sdk";
import { Pool } from "pg";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY,
webhooks: { secret: process.env.BIRD_WEBHOOK_SECRET }
});
const db = new Pool({ connectionString: process.env.DATABASE_URL });
// Prepare PostgreSQL once before serving this handler:
// CREATE TABLE bird_inbound_inbox (
// delivery_id text PRIMARY KEY, payload jsonb NOT NULL,
// received_at timestamptz NOT NULL DEFAULT now()
// );
// A separate worker owns processing and safe business retries.
export async function POST(request) {
const rawBody = await request.text();
const headers = Object.fromEntries(request.headers);
let event;
try {
event = bird.webhooks.unwrap(rawBody, headers);
} catch {
return new Response("Invalid signature", { status: 400 });
}
if (event.type !== "email.received") return new Response(null, { status: 204 });
const deliveryId = headers["webhook-id"];
if (!deliveryId) return new Response("Missing delivery ID", { status: 400 });
try {
await db.query(
`INSERT INTO bird_inbound_inbox (delivery_id, payload)
VALUES ($1, $2::jsonb) ON CONFLICT (delivery_id) DO NOTHING`,
[deliveryId, JSON.stringify(event)]
);
} catch {
return new Response("Retry later", { status: 503 });
}
return new Response(null, { status: 202 });
}
INBOUND EMAIL / TRY IT YOURSELF
An incoming message. A considered next step.
Inspect the received content, verify the event and preview durable acceptance. The booking stays unchanged until your application checks authority and availability.
Create a generated forwarding address, then configure your existing inbox to forward to it. This does not create a stored Agent Mailbox or require a DNS change.
Register and DKIM-verify a dedicated receiving subdomain, enable receiving and publish that registration’s MX records. Preserve your corporate domain’s current mail routing.
RECEIVED / rem_example_fn1042
AL
Alex Leealex@example.com
A little question about Friday.
Could we move booking FN–1042 to the afternoon? The original booking is attached.
Bird retains received messages for 30 days. Your application owns durable event acceptance, business retries and the retention of any content it stores.
Need durable threads and replies? ↗INSPECT / CONTENT & EVENT
Could we move booking FN–1042 to the afternoon?
GET /v1/email/inbound-messages/{id}/body<p>Could we move booking FN–1042 to the afternoon?</p>
GET /v1/email/inbound-messages/{id}/bodybooking.pdf
Content type: application/pdf
GET /v1/email/inbound-messages/{id}/attachments
GET /v1/email/inbound-messages/{id}/attachments/{attachment_id}From: Alex Lee <alex@example.com>
Subject: A little question about Friday.
MIME-Version: 1.0
GET /v1/email/inbound-messages/{id}/rawwebhook-id: evt_example_fn1042
{
"type": "email.received",
"timestamp": "2026-09-17T10:42:00Z",
"data": {
"inbound_message_id": "rem_example_fn1042",
"from": "alex@example.com",
"authentication": "unknown",
"spf_pass": true,
"dkim_pass": true,
"dmarc_pass": null
}
}Selected fields and content are illustrative excerpts. The event identifies stored content; it does not contain attachment bytes. Fetch the body, raw MIME or attachments through their separate reads.
Verify the signature over the raw body. Durably accept this webhook-id before acknowledging the delivery.
Example: 202 accepted after one durable inbox write. Sender authentication is unknown, so the application holds the request for review. No booking was changed and no confirmation was sent.
Example replay: the unique delivery ID already exists. No second work item is created. Business processing still needs its own safe retries.
Example: storage failed, return 503. No work was durably accepted. Repair storage and let the documented webhook retry policy redeliver the event.
Example: invalid or stale signature, return 400. Do not accept work or trust this payload. Check the signing secret and deployment before a retry.
A valid webhook signature authenticates Bird’s delivery. It does not verify the email sender. Unknown or missing authentication remains unverified; SPF or DKIM alone does not establish alignment with the visible sender.
Read the receiving setup ↗BIRD EMAILA connection worth building on.
PRODUCT OPERATING EVIDENCE
Start receiving without changing DNS.
A generated forwarding address receives mail from an existing inbox. Use a dedicated, verified receiving subdomain when the address itself should belong to your brand.
Read the product guide ↗Documented behavior; confirm current access and setup in your workspace.FIND YOUR WAY IN
Receive an event or keep a conversation?
Choose Inbound email.
Bring a parsed message and its attachments into your application workflow through events.
Set up receiving ↗Choose Agent Mailboxes.
Add a durable address, retained threads, and reply operations when the inbox is part of your product.
Explore Agent Mailboxes ↗THE COMPLETE BIRD PLATFORM
Receive the question. Connect the answer.
Bring inbound messages into your application, send a response with the Email API, or use Mailboxes when the conversation needs a home.
PARSED INBOUND MESSAGEOne received message.
Ready for your app.
Ready for your app.
- From
- Alex Lee
- Subject
- Change booking FN–1042
- Attachment
- Original booking receipt
01
Inbound This step
Alex asks to change booking FN–1042 and attaches the receipt.
THREAD / FN–1042Could we make it
the afternoon?
the afternoon?
Alex Lee · Original booking attached
Reply draft
I’ll check with the studio before changing the booking.
Your application’s review policyI’ll check with the studio before changing the booking.
02
Mailboxes ↗
Keep the thread when the workflow needs an ongoing agent conversation.
f.
FieldnotesTo: Alex Lee ⌄
Your studio visit. All in one place.
fieldnotes.BOOKING FN–1042Your studio visit.
All in one place.
Alex Lee · Friday, 14:00
Clay workshop · One guest
View your booking ↗
All in one place.
Alex Lee · Friday, 14:00Clay workshop · One guest
View your booking ↗
03
Email API ↗
Your app sends a confirmation after its booking operation succeeds.
LEARN / BUILD / OPERATEGo further with
FIELD GUIDE
Go further with
Inbound email.
FIELD GUIDEChoose an inbound email workflow
Compare event ingestion with a persistent mailbox, including retention and reply decisions.
Read the field guide →01↗02↗03↗04↗
Configurer l'e-mail entrant
Forwarding addresses, MX records, and parsed messages.
Verify webhooks
Raw-body signature verification and stable delivery IDs.
Work with attachments
List attachment metadata, then retrieve bytes by attachment ID.
Create an agent mailbox
A persistent address and conversation lifecycle.
INBOUND / YOUR EMAIL SETUPReceive the message.
Receive the message.
Plan what comes next.
Plan receiving volume, attachment handling, and application processing with the email your business sends. Talk to sales about the exact allowances your workflow needs.
Review Email plans ↗Confirm the receiving scope of your Email setup.
- Incoming traffic
- Scope message size, volume, and attachments.
- Event handling
- Plan webhook destinations and durable processing.
- Conversation needs
- Choose Mailboxes if stored threads and replies are part of the job.
Inbound email, answered.
How is this different from Mailboxes?
Inbound email turns arriving mail into events and parsed content. Mailboxes adds a persistent address and thread-oriented inbox for applications and agents that need to read and reply over time.
Can attachments trigger a workflow?
Your application can process received attachments after it handles the inbound event. Validate untrusted content and decide what is appropriate for your workflow before acting on it.
Does webhook verification prove the sender’s identity?
No. It establishes that the webhook delivery is authentic. Inspect the received email’s authentication verdicts separately before trusting the sender or taking action.
How do I prevent duplicate work?
Verify first, then durably accept work keyed by the stable webhook-id header. Business processing must also be safe to retry; an in-memory set is not sufficient.
How do I get started or speak to sales?
Start with a Bird account and follow the setup path on this page. Our sales team can help with migration, volume, or a wider product mix. Start now or talk to sales.