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: '<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:

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.

{
  "event": "email.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "email": {
    "id": "inbnd_abc123def456ghi",
    "messageId": "<unique-id@sender.com>",
    "subject": "Help with my order",
    "recipient": "support@yourdomain.com"
  },
  "endpoint": {
    "id": "endp_xyz789",
    "name": "Support Webhook",
    "type": "webhook"
  }
}