> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailofly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound webhooks

# Inbound Webhooks

When an inbound email arrives for your verified domain, Mailofly sends a `POST` request with the parsed payload to your designated webhook endpoint.

***

## Event Payload: `email.received`

```json theme={null}
{
  "event": "email.received",
  "created_at": "2026-09-11T00:45:12Z",
  "data": {
    "message_id": "inbound_msg_98234ab12",
    "from": "Sarah Connor <sarah@skynet.com>",
    "to": ["support@inbound.yourcompany.com"],
    "reply_to": ["sarah@skynet.com"],
    "subject": "Help with integration",
    "text": "Hello, I am having trouble configuring webhooks.",
    "html": "<p>Hello, I am having trouble configuring webhooks.</p>",
    "headers": {
      "message-id": "<CA+12345@mail.gmail.com>",
      "in-reply-to": "<outbound_msg_111@yourcompany.com>",
      "references": "<outbound_msg_111@yourcompany.com>"
    },
    "attachments": [
      {
        "filename": "screenshot.png",
        "content_type": "image/png",
        "size": 142050,
        "download_url": "https://api.mailofly.com/v1/inbound/attachments/att_12345"
      }
    ]
  }
}
```

***

## Next.js / Express Webhook Handler Example

```typescript theme={null}
// app/api/inbound-email/route.ts (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const body = await req.json();

  if (body.event === "email.received") {
    const { from, to, subject, text, attachments } = body.data;

    console.log(`Received email from ${from} with subject: "${subject}"`);

    // Process email into your help desk, database, or trigger an AI agent response
    // await createSupportTicket({ from, subject, text });

    return NextResponse.json({ received: true }, { status: 200 });
  }

  return NextResponse.json({ ignored: true }, { status: 200 });
}
```

***

## Response Expectation

Your webhook endpoint must return an HTTP `200 OK` or `204 No Content` within **10 seconds**. If the endpoint times out or returns a `5xx` error, Mailofly will automatically retry delivery using exponential backoff.


## Related topics

- [Configure webhook](/receiving/configure-webhook.md)
- [Introduction](/receiving/introduction.md)
- [Custom Domains](/receiving/custom-domains.md)
- [Reply to Emails](/receiving/reply-to-emails.md)
- [Attachments](/receiving/attachments.md)