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

List received inbound emails.

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
}

Scheduled Emails

Rate Limits