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:

import type { InboundWebhookPayload } from 'inboundemail'

Example Payload

const payload: InboundWebhookPayload = {
  event: 'email.received',
  timestamp: '2024-01-15T10:30:00Z',
  email: {
    id: 'inbnd_abc123def456ghi',
    messageId: '<[e-mail]>',
    from: {
      text: 'John Doe <[e-mail]>',
      addresses: [{
        name: 'John Doe',
        address: '[e-mail]'
      }]
    },
    to: {
      text: '[e-mail]',
      addresses: [{
        name: null,
        address: '[e-mail]'
      }]
    },
    recipient: '[e-mail]',
    subject: 'Help with my order',
    receivedAt: '2024-01-15T10:30:00Z',
    parsedData: {
      messageId: '<[e-mail]>',
      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/parts/0'
        }
      ]
    }
  },
  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

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:

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

WEBHOOK emailReceived

Example

{
  "event": "email.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "email": {
    "id": "inbnd_abc123def456ghi",
    "messageId": "<[e-mail]>",
    "subject": "Help with my order",
    "recipient": "[e-mail]",
    "from": {
      "text": "<string>",
      "addresses": [
        {
          "name": "<string>",
          "address": "<string>"
        }
      ]
    },
    "to": {
      "text": "<string>",
      "addresses": [
        {
          "name": "<string>",
          "address": "<string>"
        }
      ]
    },
    "parsedData": {
      "textBody": "<string>",
      "htmlBody": "<string>",
      "attachments": [
        {
          "filename": "<string>",
          "contentType": "<string>",
          "size": 123,
          "downloadUrl": "<string>"
        }
      ]
    }
  },
  "endpoint": {
    "id": "endp_xyz789",
    "name": "Support Webhook",
    "type": "webhook"
  }
}

Authorizations

Authorization · string · header · required

Your Inbound API key. Include it in the Authorization header as: Bearer

Body

application/json

Webhook payload sent when an email is received

event · string

The event type

Example:

"email.received"

timestamp · string<date-time>

Example:

"2024-01-15T10:30:00Z"

email · object

Show child attributes

endpoint · object

Show child attributes

Response

200

Webhook processed successfully