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

# Email received

> 
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.




## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/inbound/openapi.documented.yml webhook emailReceived
openapi: 3.1.0
info:
  title: Inbound Email API
  description: >+

    # Inbound API


    The Inbound API allows you to manage email infrastructure programmatically -
    domains, email addresses, webhooks, and more.


    ## Authentication


    All API requests require a Bearer token in the Authorization header:


    ```bash

    curl -H "Authorization: Bearer YOUR_API_KEY" \
      https://inbound.new/api/e2/domains
    ```


    ## Base URL


    ```

    https://inbound.new/api/e2

    ```


    ## Quick Start


    1. **Create a domain** - Register your domain with Inbound

    2. **Configure DNS** - Add the provided DNS records to your domain

    3. **Create an email address** - Set up addresses to receive emails

    4. **Create an endpoint** - Configure where emails are delivered (webhook,
    forwarding, etc.)

  version: 2.0.0
servers:
  - url: https://inbound.new
    description: Production API server
security:
  - bearerAuth: []
tags:
  - name: Webhooks
    description: Webhooks sent by Inbound to your configured endpoints when events occur.
  - name: Emails
    description: >-
      Send, list, and manage emails. Supports immediate sending, scheduling,
      replies, and retry functionality.
  - name: Mail
    description: >-
      Inbox and thread views for received emails. Filter by domain, address, or
      search.
  - name: Domains
    description: >-
      Manage domains for sending and receiving emails. Domains must be verified
      via DNS before use.
  - name: Endpoints
    description: >-
      Configure where incoming emails are delivered - webhooks, email
      forwarding, or custom handlers.
  - name: Email Addresses
    description: Create and manage email addresses on your verified domains.
  - name: Attachments
    description: Download email attachments using authenticated requests.
paths: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Inbound API key. Include it in the Authorization header as: Bearer
        <your-api-key>

````