Skip to content

Inbound Email

Receive and process incoming emails on your verified domains. PostStack parses inbound messages and forwards them to your webhook endpoint or stores them for API retrieval.

Enabling Inbound Email

Enable inbound email on a verified domain by updating its settings. You will also need to add an MX record pointing to PostStack:

typescript
// Enable inbound email on a domain
const domain = await poststack.domains.update('dom_abc123def456', {
  inbound_enabled: true,
});

Add the following MX record to your DNS to receive inbound emails:

TypeNameValuePriority
MXyourdomain.cominbound.poststack.dev10
GET
/inbound-emails

List received inbound emails with pagination. Filter by domain or date range.

json
{
  "emails": [
    {
      "id": "in_abc123def456ghi789",
      "from": "sender@external.com",
      "to": ["support@yourdomain.com"],
      "subject": "Need help with my account",
      "text": "Hi, I need help resetting my password...",
      "has_attachments": true,
      "received_at": "2026-03-23T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 48,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}
GET
/inbound-emails/:id

Retrieve a single inbound email with full content and attachment metadata.

json
{
  "id": "in_abc123def456ghi789",
  "from": "sender@external.com",
  "to": ["support@yourdomain.com"],
  "cc": [],
  "subject": "Need help with my account",
  "html": "<p>Hi, I need help resetting my password...</p>",
  "text": "Hi, I need help resetting my password...",
  "headers": {
    "message-id": "<abc123@external.com>",
    "date": "Mon, 23 Mar 2026 10:00:00 +0000"
  },
  "attachments": [
    {
      "id": 1,
      "filename": "screenshot.png",
      "content_type": "image/png",
      "size": 24576
    }
  ],
  "received_at": "2026-03-23T10:00:00.000Z"
}
GET
/inbound-emails/:id/attachments

List all attachments for an inbound email.

json
{
  "attachments": [
    {
      "id": 1,
      "filename": "screenshot.png",
      "content_type": "image/png",
      "size": 24576
    },
    {
      "id": 2,
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "size": 102400
    }
  ]
}
GET
/inbound-emails/:id/attachments/:aid

Download a specific attachment. Returns the raw file content with the appropriate Content-Type header.

typescript
const data = await poststack.inboundEmails.downloadAttachment(
  'in_abc123def456ghi789',
  1,
);
POST
/inbound-emails/:id/reply

Reply to an inbound email. The reply is sent as a new outbound email with proper In-Reply-To headers.

json
{
  "from": "Support <support@yourdomain.com>",
  "html": "<p>Hi, I've reset your password. Please check your email.</p>",
  "text": "Hi, I've reset your password. Please check your email.",
  "cc": ["team@yourdomain.com"]
}
POST
/inbound-emails/:id/forward

Forward an inbound email to one or more recipients. Includes the original email content.

json
{
  "from": "Support <support@yourdomain.com>",
  "to": ["escalation@yourdomain.com"],
  "message": "Please take a look at this support request."
}

Inbound Webhooks

Subscribe to the email.inbound webhook event to receive real-time notifications when inbound emails arrive:

typescript
// Create a webhook for inbound email events
await poststack.webhooks.create({
  url: 'https://yourdomain.com/webhooks/inbound',
  events: ['email.inbound'],
});

Webhook Payload

The inbound webhook payload includes the parsed email content:

json
{
  "id": "evt_inbound_abc123",
  "type": "email.inbound",
  "timestamp": "2026-03-23T10:00:00.000Z",
  "data": {
    "id": "in_abc123def456ghi789",
    "from": "sender@external.com",
    "to": ["support@yourdomain.com"],
    "subject": "Need help with my account",
    "text": "Hi, I need help resetting my password...",
    "html": "<p>Hi, I need help resetting my password...</p>",
    "has_attachments": true
  }
}