[Email](/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. [Start now ↗](/dashboard/signup?returnTo=%2Fdashboard%2Fw%2Femail%2Finbound) [Talk to sales ↗](/demo?product=inbound) BIRD / INBOUND Illustrative experience 01 Receive the email 02 Read the details 03 Create the work Replay Incoming email AL Alex Lee To: studio@fieldnotes.example ### A little question about Friday. Could we move booking FN–1042 to the afternoon? The original booking is attached. booking.pdf Application reads the retained attachment Receiving event Example · no request is made event: email.received message: rem_example_fn1042 Verify the event. Read the content. Start the application workflow. Incoming email AL Alex Lee To: studio@fieldnotes.example ### A little question about Friday. Could we move booking FN–1042 to the afternoon? The original booking is attached. booking.pdf Application reads the retained attachment Content available to your application Example · no request is made from alex@example.com subject 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 application Example · no request is made from alex@example.com subject 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 item CUSTOMER SERVICE ### One request. The details included. Customer Alex Lee Reference FN–1042 Request Move the visit to the afternoon Context Original booking attached Ready for your workflow **Example content and data. Nothing is sent or changed in a live account. Use the stage controls to explore.** [Meet Bird’s customers ↗](/customers) Companies that trust Bird across their communications. - [Airwallex](/customers/airwallex) - Uber - [Zillow](/customers/zillow) - [Glovo](/customers/glovo) - PayPal - Adobe [Read Bird customer stories](/customers) WHAT IT MEANS FOR YOUR CUSTOMER ## 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. 01 / Receive ### Give the request a way in. Use a forwarding address or a receiving subdomain to bring the customer’s email into your application. 02 / Understand ### Work with the content. Read parsed text, message details, and attachments so your workflow starts with what the customer supplied. 03 / Act ### 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. [Start now ↗](/dashboard/signup?returnTo=%2Fdashboard%2Fw%2Femail%2Finbound) [Talk to sales ↗](/demo?product=inbound) 01 [Choose how mail arrives ↗ Start with forwarding or prepare a receiving subdomain.](/docs/guides/email/receiving-email) 02 [Prepare the webhook ↗ Verify the raw payload and retain work before acknowledgment.](/docs/guides/webhooks) 03 [Connect the application ↗ Handle the message and supported attachments deliberately.](/docs/guides/webhooks) ## 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 →](/docs/guides/email/receiving-email) **JavaScript**: `npm install @messagebird/sdk pg` File: `app/api/webhooks/route.js` ```javascript import { 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 }); } ``` Examples: [JavaScript](/fr-fr/inbound-email-api.js.md) ## 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. The example message, content representations and receiving guide remain available without JavaScript. Interactive processing requires JavaScript. Receiving setup Generated forwarding address Own receiving subdomain Webhook delivery signature Valid signature, example Invalid or stale signature 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 Lee alex@example.com ### A little question about Friday. Could we move booking FN–1042 to the afternoon? The original booking is attached. PARSED ATTACHMENT / EXAMPLE booking.pdf Original reservation: Friday, 10:00. Read attachment metadata, then fetch binary content separately by message and attachment ID. Preview application handling ↗ Try storage failure Replay the same event Reset 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? ↗](/agent-mailboxes) INSPECT / CONTENT & EVENT Inspect a representation Plain-text body Original HTML body Attachment metadata Original MIME Webhook envelope 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 ↗](/docs/guides/email/receiving-email) **Interactive illustration. The durable inbox, replies and failures are simulated; no account, database or booking is changed.** ## 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 ↗](/docs/guides/email/receiving-email) FIND YOUR WAY IN ## Receive an event or keep a conversation? Receive and process ### Choose Inbound email. Bring a parsed message and its attachments into your application workflow through events. [Set up receiving ↗](/docs/guides/email/receiving-email) Keep a lasting conversation ### Choose Agent Mailboxes. Add a durable address, retained threads, and reply operations when the inbox is part of your product. [Explore Agent Mailboxes ↗](/agent-mailboxes) ### The details behind your setup #### Start without DNS Use a generated forwarding address to receive mail forwarded from an existing inbox. #### Receive on your domain Use a dedicated receiving subdomain and the exact generated MX records after domain verification. #### Choose persistent Mailboxes Use Agent Mailboxes when your application needs addresses, retained threads, and replies as an ongoing conversation. #### Own storage and retries Bird retains received messages for 30 days. Verify the raw webhook, durably accept each webhook-id once, fetch bodies or attachment bytes by inbound message ID, and keep only the content your application needs under its own retention policy. 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 MESSAGE One received message. Ready for your app. From Alex Lee Subject Change booking FN–1042 Attachment Original booking receipt Your application consumes the event 01 ### Inbound This step Alex asks to change booking FN–1042 and attaches the receipt. [THREAD / FN–1042 Could we make it the afternoon? Alex Lee · Original booking attached Reply draft I’ll check with the studio before changing the booking. Your application’s review policy](/agent-mailboxes) 02 ### [Mailboxes ↗](/agent-mailboxes) Keep the thread when the workflow needs an ongoing agent conversation. [Your studio visit. All in one place. fieldnotes. BOOKING FN–1042 Your studio visit. All in one place. Alex Lee · Friday, 14:00 Clay workshop · One guest View your booking ↗](/email-api) 03 ### [Email API ↗](/email-api) Your app sends a confirmation after its booking operation succeeds. BUILD YOUR BIRD SETUP A useful next connection. [Agent mailboxes ↗ Keep the thread Give an agent or app a persistent conversation.](/agent-mailboxes) [Sending domains ↗ Receive on your identity Prepare a domain your business owns.](/email-domain-authentication) [Email templates ↗ Make the response yours Use a consistent design when your application replies.](/email-template-api) [Email analytics ↗ Follow outgoing replies Connect your sent-email record to delivery outcomes.](/email-analytics) Pair incoming email with the Email API for replies, or use Mailboxes when an application needs durable addresses and threads. Keep the choice aligned with the workflow you are building. [Plan your complete Bird setup ↗](/demo?product=inbound) ## Go further with Inbound email. [FIELD GUIDE Choose an inbound email workflow Compare event ingestion with a persistent mailbox, including retention and reply decisions. Read the field guide →](/guides/inbound-email-vs-agent-mailboxes) [01 Set up inbound email Forwarding addresses, MX records, and parsed messages. ↗](/docs/guides/email/receiving-email) [02 Verify webhooks Raw-body signature verification and stable delivery IDs. ↗](/docs/guides/webhooks) [03 Work with attachments List attachment metadata, then retrieve bytes by attachment ID. ↗](/docs/api/reference/list-inbound-message-attachments) [04 Create an agent mailbox A persistent address and conversation lifecycle. ↗](/docs/get-started/agent-mailboxes) ### Choose your email integration [Email API overview ↗](/email-api) [SMTP relay ↗](/smtp-service) [Inbound email ↗](/inbound-email-api) [Agent mailboxes ↗](/agent-mailboxes) ## 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 ↗](/products/email/pricing) YOUR INBOUND EMAIL SETUP Receiving + processing 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. ## Turn the next reply into a useful next step. [Explore the whole Bird platform ↗](/)