Domains

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

POST/v1/domains

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.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Body

domainstringrequired

Fully qualified domain name (e.g. "mail.example.com")

regionstringoptional

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).

POST /v1/domains

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

Response

{
  "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/domains

List all domains belonging to the authenticated workspace.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

GET /v1/domains

curl https://api.posthawk.dev/v1/domains \
  -H "Authorization: Bearer your_api_key"

Response

{
  "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/:id

Get details of a specific domain including DNS records.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

GET /v1/domains/:id

curl https://api.posthawk.dev/v1/domains/{id} \
  -H "Authorization: Bearer your_api_key"

Response

{
  "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/:id

Delete a domain and clean up all associated SES identities.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

DELETE /v1/domains/:id

curl -X DELETE https://api.posthawk.dev/v1/domains/{id} \
  -H "Authorization: Bearer your_api_key"

Response

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

POST/v1/domains/:id/verify

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

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

POST /v1/domains/:id/verify

curl -X POST https://api.posthawk.dev/v1/domains/{id}/verify \
  -H "Authorization: Bearer your_api_key"

Response

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

POST/v1/domains/:id/receiving/enable

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

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

POST /v1/domains/:id/receiving/enable

curl -X POST https://api.posthawk.dev/v1/domains/{id}/receiving/enable \
  -H "Authorization: Bearer your_api_key"

Response

{
  "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/disable

Disable inbound email receiving for a domain.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

POST /v1/domains/:id/receiving/disable

curl -X POST https://api.posthawk.dev/v1/domains/{id}/receiving/disable \
  -H "Authorization: Bearer your_api_key"

Response

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

PATCH/v1/domains/:id/webhook

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

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

Body

webhookUrlstring | nullrequired

Webhook URL to forward inbound emails to, or null to disable

PATCH /v1/domains/:id/webhook

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

Response

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

POST/v1/domains/:id/webhook/test

Send a test payload to the configured webhook URL to verify it is working. Returns the HTTP status your endpoint responded with (SSRF-protected — blocked URLs return status 0 with an error).

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

POST /v1/domains/:id/webhook/test

curl -X POST https://api.posthawk.dev/v1/domains/{id}/webhook/test \
  -H "Authorization: Bearer your_api_key"

Response

{
  "success": true,
  "status": 200,
  "statusText": "OK"
}

POST/cloud-domains/:id/bimi

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. JWT-authenticated (dashboard) endpoint.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your JWT.

Path Parameters

idstringrequired

Domain UUID

Body

svgPathstringrequired

Public path to the SVG file in your storage

svgUrlstringrequired

Public HTTPS URL of the SVG-Tiny PS logo

vmcCertUrlstringrequired

HTTPS URL of the VMC certificate (.pem)

POST /cloud-domains/:id/bimi

curl -X POST https://api.posthawk.dev/cloud-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

{
  "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/cloud-domains/:id/bimi/verify

Verify the BIMI DNS record is published correctly and the SVG/VMC are reachable. JWT-authenticated (dashboard) endpoint.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your JWT.

Path Parameters

idstringrequired

Domain UUID

POST /cloud-domains/:id/bimi/verify

curl -X POST https://api.posthawk.dev/cloud-domains/{id}/bimi/verify \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "domain": "mail.example.com",
    "bimi_check": { "dmarc_ok": true, "bimi_ok": true, "message": "BIMI verified" },
    "dns_records": [ ... ]
  },
  "message": "BIMI verified"
}

DELETE/cloud-domains/:id/bimi

Disable BIMI for a domain. JWT-authenticated (dashboard) endpoint.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your JWT.

Path Parameters

idstringrequired

Domain UUID

DELETE /cloud-domains/:id/bimi

curl -X DELETE https://api.posthawk.dev/cloud-domains/{id}/bimi \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "success": true,
  "data": {
    "id": "domain-uuid",
    "domain": "mail.example.com",
    "bimi_enabled": false,
    "dns_records": [ ... ]
  },
  "message": "BIMI disabled"
}

PATCH/v1/domains/:id/limits

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.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

idstringrequired

Domain UUID

Body

maxDailyEmailsnumber | nulloptional

Maximum emails per day from this domain. Null for unlimited.

maxMonthlyEmailsnumber | nulloptional

Maximum emails per month from this domain. Null for unlimited.

PATCH /v1/domains/:id/limits

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

Response

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