Inbound Email

Receive and process incoming emails via domain configuration and webhook delivery.

Posthawk supports receiving inbound emails through two providers:

1. Cloudflare Email Routing — configure MX records to route emails to your Posthawk instance
2. AWS SES — set up a receipt rule to forward to an SNS topic, then configure the webhook

For each provider, create an inbound domain in the dashboard, configure the required DNS records, then verify the domain. Incoming emails are parsed and optionally forwarded to your webhook URL.

POST/inbound/domainsJWT

Parameter	Type	In	Description
`domain`required	`string`	body	Fully qualified domain name
`provider`	`string`	body	"cloudflare" \| "aws_ses" \| "custom". Defaults to "cloudflare".
`webhookUrl`	`string`	body	URL to forward parsed emails to

Request

bash

curl -X POST https://your-posthawk-instance.com/inbound/domains \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "domain": "mail.yourdomain.com",
    "provider": "cloudflare",
    "webhookUrl": "https://yourapp.com/api/incoming-email"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "uuid",
    "domain": "mail.yourdomain.com",
    "provider": "cloudflare",
    "is_verified": false,
    "webhook_url": "https://yourapp.com/api/incoming-email"
  },
  "message": "Inbound domain created. Configure MX records to start receiving emails."
}

GET/inbound/domainsJWT

List all configured inbound domains.

Response

json

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "domain": "mail.yourdomain.com",
      "provider": "cloudflare",
      "is_verified": true,
      "is_active": true
    }
  ]
}

POST/inbound/domains/:id/verifyJWT

Verify domain ownership after DNS records are configured.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID

Response

json

{
  "success": true,
  "data": { "id": "uuid", "is_verified": true },
  "message": "Domain verified successfully"
}

GET/inbound/domains/:idJWT

Get details of a specific inbound domain.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID

Response

json

{
  "success": true,
  "data": {
    "id": "uuid",
    "domain": "mail.yourdomain.com",
    "provider": "cloudflare",
    "is_verified": true,
    "is_active": true,
    "webhook_url": "https://yourapp.com/api/incoming-email"
  }
}

PATCH/inbound/domains/:idJWT

Update an inbound domain — change the webhook URL or toggle active status.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID
`webhookUrl`	`string`	body	New webhook URL for email forwarding
`isActive`	`boolean`	body	Enable or disable inbound processing for this domain

Request

bash

curl -X PATCH https://your-posthawk-instance.com/inbound/domains/uuid \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "webhookUrl": "https://yourapp.com/api/new-webhook",
    "isActive": true
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "uuid",
    "domain": "mail.yourdomain.com",
    "webhook_url": "https://yourapp.com/api/new-webhook",
    "is_active": true
  },
  "message": "Inbound domain updated"
}

DELETE/inbound/domains/:idJWT

Delete an inbound domain and stop receiving emails for it.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID

Response

json

{
  "success": true,
  "message": "Inbound domain deleted"
}

GET/inbound/emailsJWT

List received inbound emails with optional filtering and pagination.

Parameter	Type	In	Description
`domainId`	`string`	query	Filter by inbound domain
`limit`	`number`	query	Pagination limit
`offset`	`number`	query	Pagination offset

Response

json

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "from_address": "sender@example.com",
      "to_addresses": ["you@yourdomain.com"],
      "subject": "Hello!",
      "received_at": "2025-06-01T12:00:00Z"
    }
  ],
  "total": 1
}

GET/inbound/emails/:idJWT

Get the full details of a specific inbound email including body, headers, and attachments.

Parameter	Type	In	Description
`id`required	`string`	path	Inbound email UUID

Response

json

{
  "success": true,
  "data": {
    "id": "uuid",
    "from_address": "sender@example.com",
    "from_name": "John Doe",
    "to_addresses": ["you@yourdomain.com"],
    "subject": "Hello!",
    "html": "<p>Email body here</p>",
    "text": "Email body here",
    "attachments": [],
    "received_at": "2025-06-01T12:00:00Z",
    "webhook_status": "delivered"
  }
}

Scheduled Emails

Rate Limits