---
title: "Email Received"
method: POST
path: "emailReceived"
tags: ["Webhooks"]
---

# Email Received

`POST emailReceived` (webhook)

When emails arrive at your configured addresses, Inbound sends a webhook to your endpoint with the complete email data.

## Webhook Payload Structure

We provide a fully typed webhook payload for you to use in your endpoints:

```typescript
import type { InboundWebhookPayload } from 'inboundemail'
```

### Example Payload

```typescript
const payload: InboundWebhookPayload = {
  event: 'email.received',
  timestamp: '2024-01-15T10:30:00Z',
  email: {
    id: 'inbnd_abc123def456ghi',
    messageId: '<unique-id@sender.com>',
    from: {
      text: 'John Doe <john@sender.com>',
      addresses: [{
        name: 'John Doe',
        address: 'john@sender.com'
      }]
    },
    to: {
      text: 'support@yourdomain.com',
      addresses: [{
        name: null,
        address: 'support@yourdomain.com'
      }]
    },
    recipient: 'support@yourdomain.com',
    subject: 'Help with my order',
    receivedAt: '2024-01-15T10:30:00Z',
    parsedData: {
      messageId: '<unique-id@sender.com>',
      date: new Date('2024-01-15T10:30:00Z'),
      subject: 'Help with my order',
      from: { /* ... */ },
      to: { /* ... */ },
      cc: null,
      bcc: null,
      replyTo: null,
      textBody: 'Hello, I need help with my recent order...',
      htmlBody: '<p>Hello, I need help with my recent order...</p>',
      attachments: [
        {
          filename: 'order-receipt.pdf',
          contentType: 'application/pdf',
          size: 45678,
          contentId: '<att_abc123>',
          contentDisposition: 'attachment',
          downloadUrl: 'https://inbound.new/api/e2/attachments/inbnd_abc123/order-receipt.pdf'
        }
      ]
    }
  },
  endpoint: {
    id: 'endp_xyz789',
    name: 'Support Webhook',
    type: 'webhook'
  }
}
```

## Webhook Security

Always verify webhook requests before processing them to prevent unauthorized access.

### Verification Headers

Every webhook request includes security headers:

| Header | Description |
|--------|-------------|
| `X-Webhook-Verification-Token` | Unique verification token for your endpoint |
| `X-Endpoint-ID` | ID of the endpoint that triggered this webhook |
| `X-Webhook-Event` | Event type (e.g., `email.received`) |
| `X-Webhook-Timestamp` | ISO 8601 timestamp of when the webhook was sent |

### Verifying with the SDK

```typescript
import { Inbound, verifyWebhookFromHeaders } from 'inboundemail'

const inbound = new Inbound(process.env.INBOUND_API_KEY!)

export async function POST(request: Request) {
  // Verify webhook authenticity before processing
  const isValid = await verifyWebhookFromHeaders(request.headers, inbound)
  
  if (!isValid) {
    return new Response('Unauthorized', { status: 401 })
  }
  
  // Process the verified webhook payload
  const payload: InboundWebhookPayload = await request.json()
  const { email } = payload
  
  console.log('Received verified email:', email.subject)
  
  return new Response('OK', { status: 200 })
}
```

## Downloading Attachments

Each attachment includes a `downloadUrl` for direct file access:

```typescript
// Download attachments from webhook payload
for (const attachment of email.parsedData.attachments) {
  const response = await fetch(attachment.downloadUrl, {
    headers: {
      'Authorization': `Bearer ${process.env.INBOUND_API_KEY}`
    }
  })
  
  if (response.ok) {
    const fileBuffer = await response.arrayBuffer()
    // Process the file...
  }
}
```

> **Note:** Authentication via API key in the Authorization header is required to download attachments.

## Payload

- object
  - `event` string — The event type
  - `timestamp` string, date-time
  - `email` object
    - `id` string
    - `messageId` string
    - `subject` string
    - `recipient` string
    - `from` object
      - `text` string
      - `addresses` object[]
        - `name` string, nullable
        - `address` string
    - `to` object
      - `text` string
      - `addresses` object[]
        - `name` string, nullable
        - `address` string
    - `parsedData` object
      - `textBody` string, nullable
      - `htmlBody` string, nullable
      - `attachments` object[]
        - `filename` string
        - `contentType` string
        - `size` integer
        - `downloadUrl` string
  - `endpoint` object
    - `id` string
    - `name` string
    - `type` string

## Acknowledgement `200`

Webhook processed successfully

---

[API](https://skmtc.dev/inboundemail/apis/inbound-email-api.md) · [All operations](https://skmtc.dev/inboundemail/apis/inbound-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inboundemail/inbound-email-api/revisions/04a8a5e5040d/schema)