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 (RSA 2048-bit, selector "posthawk") in the selected SES region and returns DNS records to configure. After DNS propagates, call /verify to flip the domain to sending_enabled=true. The dkim_status field transitions through: pending → verified | failed | temporary_failure.

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". Currently 2 supported regions: us-east-1 (US East, N. Virginia), eu-north-1 (EU, Stockholm). Inbound receiving always uses eu-west-1 internally (Stockholm doesn't support SES inbound).

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"
}

POST/v1/domains/:id/bimiJWT

Enable BIMI (Brand Indicators for Message Identification) for a domain. Surfaces your brand logo in supported inboxes (Gmail, Yahoo, Apple Mail). Requires a Verified Mark Certificate (VMC) and an SVG-Tiny PS logo hosted on HTTPS. Returns the DNS TXT record to add.

Parameter	Type	In	Description
`id`required	`string`	path	Domain UUID
`svgPath`required	`string`	body	Public path to the SVG file in your storage
`svgUrl`required	`string`	body	Public HTTPS URL of the SVG-Tiny PS logo
`vmcCertUrl`required	`string`	body	HTTPS URL of the VMC certificate (.pem)

Request

bash

curl -X POST https://api.posthawk.dev/v1/domains/domain-uuid/bimi \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JWT" \
  -d '{
    "svgPath": "logos/posthawk.svg",
    "svgUrl": "https://posthawk.dev/logos/posthawk.svg",
    "vmcCertUrl": "https://posthawk.dev/certs/vmc.pem"
  }'

Response

json

{
  "success": true,
  "data": {
    "bimi_enabled": true,
    "dns_record": {
      "type": "TXT",
      "name": "default._bimi.example.com",
      "value": "v=BIMI1; l=https://posthawk.dev/logos/posthawk.svg; a=https://posthawk.dev/certs/vmc.pem"
    }
  },
  "message": "BIMI enabled. Add the DNS record and click Verify when DNS has propagated."
}

POST/v1/domains/:id/bimi/verifyJWT

Verify the BIMI DNS record is published correctly and the SVG/VMC are reachable.

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

Response

json

{
  "success": true,
  "data": {
    "bimi_check": { "ok": true, "message": "BIMI verified" },
    "bimi_verified_at": "2026-04-28T11:30:00Z"
  },
  "message": "BIMI verified"
}

DELETE/v1/domains/:id/bimiJWT

Disable BIMI for a domain.

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

Response

json

{
  "success": true,
  "data": { "bimi_enabled": false },
  "message": "BIMI disabled"
}

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"
}

Tenant Reputation (Cloud)

Webhooks