Domains

Programmatically manage sending domains — add, verify, configure inbound receiving, set up webhooks, and enforce per-domain sending limits. Cloud edition only.

POST/v1/domainsAPI Key

Register a new sending domain. Creates a BYODKIM identity in the selected SES region and returns DNS records to configure.

Parameter	Type	In	Description
`domain`required	`string`	body	Fully qualified domain name (e.g. "mail.example.com")
`region`	`string`	body	AWS SES region for sending. Defaults to "us-east-1". Options: us-east-1, eu-north-1

Request

bash

curl -X POST https://api.posthawk.dev/v1/domains \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "domain": "mail.example.com",
    "region": "us-east-1"
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "domain": "mail.example.com",
    "ses_region": "us-east-1",
    "dkim_status": "pending",
    "sending_enabled": false,
    "receiving_enabled": false,
    "dns_records": [
      { "type": "TXT", "name": "posthawk._domainkey.mail.example.com", "value": "v=DKIM1; k=rsa; p=MIIBIj..." },
      { "type": "TXT", "name": "mail.example.com", "value": "v=spf1 include:amazonses.com ~all" },
      { "type": "MX", "name": "mail.example.com", "value": "10 feedback-smtp.us-east-1.amazonses.com" }
    ]
  },
  "message": "Domain registered. Add the DNS records to verify ownership."
}

GET/v1/domainsAPI Key

List all domains belonging to the authenticated workspace.

Response

json

{
  "success": true,
  "data": [
    {
      "id": "domain-uuid",
      "domain": "mail.example.com",
      "ses_region": "us-east-1",
      "dkim_status": "verified",
      "sending_enabled": true,
      "receiving_enabled": false,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

GET/v1/domains/:idAPI Key

Get details of a specific domain including DNS records.

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

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "domain": "mail.example.com",
    "ses_region": "us-east-1",
    "dkim_status": "verified",
    "sending_enabled": true,
    "receiving_enabled": false,
    "webhook_url": null,
    "dns_records": [ ... ]
  }
}

DELETE/v1/domains/:idAPI Key

Delete a domain and clean up all associated SES identities.

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

Response

json

{
  "success": true,
  "message": "Domain removed"
}

POST/v1/domains/:id/verifyAPI Key

Trigger a verification check for a domain. Returns the current verification status.

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

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "dkim_status": "verified",
    "sending_enabled": true
  },
  "message": "Domain verified and ready for sending"
}

POST/v1/domains/:id/receiving/enableAPI Key

Enable inbound email receiving for a domain. Creates the identity in the receiving region and sets up a receipt rule.

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

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "receiving_enabled": true,
    "mx_record": { "type": "MX", "name": "mail.example.com", "value": "10 inbound-smtp.eu-west-1.amazonaws.com" }
  },
  "message": "Receiving enabled. Add the MX record to start receiving emails."
}

POST/v1/domains/:id/receiving/disableAPI Key

Disable inbound email receiving for a domain.

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

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "receiving_enabled": false
  },
  "message": "Receiving disabled"
}

PATCH/v1/domains/:id/webhookAPI Key

Set or update the webhook URL for inbound email forwarding. Set to null to disable.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID
`webhookUrl`required	`string \| null`	body	Webhook URL to forward inbound emails to, or null to disable

Request

bash

curl -X PATCH https://api.posthawk.dev/v1/domains/domain-uuid/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{ "webhookUrl": "https://yourapp.com/api/incoming-email" }'

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "webhook_url": "https://yourapp.com/api/incoming-email"
  },
  "message": "Webhook updated"
}

POST/v1/domains/:id/webhook/testAPI Key

Send a test payload to the configured webhook URL to verify it is working.

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

Response

json

{
  "success": true,
  "statusCode": 200,
  "message": "Webhook test successful"
}

PATCH/v1/domains/:id/limitsAPI Key

Set per-domain sending limits. Emails exceeding these limits will be rejected with a clear error message. Set to null to remove a limit (unlimited). Limits are enforced on both the REST API and SMTP relay.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID
`maxDailyEmails`	`number \| null`	body	Maximum emails per day from this domain. Null for unlimited.
`maxMonthlyEmails`	`number \| null`	body	Maximum emails per month from this domain. Null for unlimited.

Request

bash

curl -X PATCH https://api.posthawk.dev/v1/domains/domain-uuid/limits \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "maxDailyEmails": 1000,
    "maxMonthlyEmails": 25000
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "domain": "mail.example.com",
    "max_daily_emails": 1000,
    "max_monthly_emails": 25000
  },
  "message": "Sending limits updated"
}

Reputation

Webhooks