Domains

Add and verify domains. PostStack requires domain verification via DNS records (SPF, DKIM, DMARC) before you can send emails. Supports region selection, TLS enforcement, tracking domains, BIMI records, inbound email, dedicated IPs, DMARC reporting, and automatic verification.

POST

/domains

Add a new domain. Optionally specify a region, TLS mode, and return path. Returns the DNS records you need to configure.

json

{
  "name": "yourdomain.com",
  "region": "eu-west-1",
  "custom_return_path": "bounce.yourdomain.com",
  "open_tracking": true,
  "click_tracking": true,
  "tls_mode": "enforced"
}

GET

/domains

List all domains for your account with their verification status.

json

{
  "domains": [
    {
      "id": "dom_abc123def456",
      "name": "yourdomain.com",
      "status": "verified",
      "region": "eu-west-1",
      "created_at": "2026-03-23T10:00:00.000Z"
    },
    {
      "id": "dom_ghi789jkl012",
      "name": "staging.yourdomain.com",
      "status": "pending",
      "region": "eu-west-1",
      "created_at": "2026-03-24T10:00:00.000Z"
    }
  ]
}

GET

/domains/:id

Retrieve a single domain with its DNS records and verification status for each record.

json

{
  "domain": {
    "id": "dom_abc123def456",
    "name": "yourdomain.com",
    "status": "verified",
    "region": "eu-west-1",
    "tls_mode": "enforced",
    "open_tracking": true,
    "click_tracking": true,
    "catch_all": false,
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "yourdomain.com",
        "value": "v=spf1 include:spf.poststack.dev ~all",
        "purpose": "spf",
        "verified": true
      },
      {
        "type": "TXT",
        "name": "poststack._domainkey.yourdomain.com",
        "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSI...",
        "purpose": "dkim",
        "verified": true
      },
      {
        "type": "TXT",
        "name": "_dmarc.yourdomain.com",
        "value": "v=DMARC1; p=none;",
        "purpose": "dmarc",
        "verified": true
      }
    ],
    "created_at": "2026-03-23T10:00:00.000Z"
  }
}

PATCH

/domains/:id

Update domain settings including tracking, TLS mode, inbound email, catch-all, and BIMI.

json

{
  "open_tracking": true,
  "click_tracking": true,
  "tls_mode": "enforced",
  "tracking_domain": "track.yourdomain.com",
  "inbound_enabled": true,
  "catch_all": true,
  "bimi_logo_url": "https://yourdomain.com/.well-known/bimi/logo.svg"
}

DELETE

/domains/:id

Remove a domain from your account. This does not affect emails already sent.

json

{
  "success": true
}

POST

/domains/:id/verify

Trigger DNS verification for a pending domain. PostStack checks all required DNS records.

json

{
  "queued": true,
  "domain": {
    "id": 42,
    "name": "send.acme.io",
    "status": "pending",
    "dnsRecords": [ ... ]
  }
}

Rotating the DKIM key

Rotate a domain’s DKIM signing key if it may have been exposed, or as routine hygiene. Rotation happens in three phases and never interrupts your sending — the new key is published under a new selector, so both keys are valid at once and there is no moment where mail is signed with a key your recipients cannot resolve.

Start. PostStack generates a new keypair under a new selector and gives you one TXT record to publish. Your current key keeps signing. A rotation you start and never finish changes nothing.
Switch over. Once the new record is verifiably published, PostStack starts signing with it. This happens automatically about 30 minutes after we first see the record — we read your authoritative nameservers directly, while your recipients’ mail servers use recursive resolvers that lag behind. Call the activate endpoint to switch sooner.
Retire. The old record stays published for 7 days after switch-over, then PostStack removes it (and removes it from your DNS provider if you have one connected).

Do not delete the old record early. Mail you sent before the switch-over is signed with the old key, and a receiving server still retrying one of those messages will look the key up at delivery time. Removing it turns those messages into DKIM failures.

POST

/domains/:id/dkim/rotate

Start a DKIM key rotation. Generates a new keypair under a new selector and returns the TXT record to publish. Your current key keeps signing until the rotation is activated.

json

{
  "rotation": {
    "domainId": 42,
    "state": "pending_dns",
    "activeSelector": "poststack",
    "pendingSelector": "ps-20260810-a1b2",
    "pendingRecordName": "ps-20260810-a1b2._domainkey.send.acme.io",
    "pendingRecordValue": "v=DKIM1; k=rsa; h=sha256; p=MIIBIjANBg...",
    "startedAt": "2026-08-10T09:00:00.000Z",
    "publishedAt": null,
    "activatesAfter": null,
    "retiredSelector": null,
    "retireAfter": null
  }
}

POST

/domains/:id/dkim/rotate/activate

Switch over to the staged key. Returns 409 if the new record is missing or does not match the key PostStack generated, and 503 if DNS could not be read — in neither case is anything changed. Pass ?force=true to skip the propagation wait (never the DNS check).

json

{
  "rotation": {
    "domainId": 42,
    "state": "retiring",
    "activeSelector": "ps-20260810-a1b2",
    "pendingSelector": null,
    "retiredSelector": "poststack",
    "retireAfter": "2026-08-17T09:30:00.000Z"
  }
}

DELETE

/domains/:id/dkim/rotate

Abandon a staged rotation and remove its DNS record. Safe at any point before switch-over — the staged key was never signing anything.

json

{
  "rotation": {
    "domainId": 42,
    "state": "idle",
    "activeSelector": "poststack",
    "pendingSelector": null
  }
}

POST

/domains/:id/ip

Assign a dedicated IP address to a domain. The IP must be allocated to your account.

json

{
  "ipAddressId": 1
}

DELETE

/domains/:id/ip

Remove the dedicated IP assignment from a domain. The domain will revert to using the shared IP pool.

json

{
  "success": true
}

DMARC Reporting

Monitor your domain's email authentication with DMARC reports. PostStack collects and aggregates DMARC reports sent by receiving mail servers to help you identify authentication failures and unauthorized senders.

GET

/domains/:id/dmarc/reports

List aggregated DMARC reports for a domain with pagination.

json

{
  "reports": [
    {
      "id": 1,
      "org_name": "google.com",
      "date_range_begin": "2026-03-22T00:00:00.000Z",
      "date_range_end": "2026-03-23T00:00:00.000Z",
      "total_count": 1250,
      "pass_count": 1248,
      "fail_count": 2
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 15,
    "totalPages": 1
  }
}

GET

/domains/:id/dmarc/stats

Get aggregated DMARC statistics for a domain. Optionally specify the number of days to look back (default: 30).

json

{
  "total_messages": 45000,
  "pass_rate": 99.7,
  "failed_messages": 135,
  "daily_stats": [
    { "date": "2026-03-22", "pass": 1500, "fail": 3 },
    { "date": "2026-03-23", "pass": 1480, "fail": 1 }
  ]
}

GET

/domains/:id/dmarc/sources

List the IP addresses sending email for your domain, with pass/fail counts for each source.

json

{
  "sources": [
    {
      "source_ip": "198.51.100.1",
      "org_name": "poststack.dev",
      "count": 12500,
      "pass_count": 12500,
      "fail_count": 0
    },
    {
      "source_ip": "203.0.113.50",
      "org_name": null,
      "count": 5,
      "pass_count": 0,
      "fail_count": 5
    }
  ]
}

Region Selection

PostStack is an EU-only platform. All sending traffic egresses from a single region:

Region	Location
`eu-west-1`	Europe (Helsinki, Finland)

TLS Mode

Control the TLS encryption requirement when delivering emails:

Mode	Description
`opportunistic`	Use TLS when available, fall back to plaintext (default)
`enforced`	Require TLS — emails will fail if the recipient server does not support TLS

Auto-Verification

PostStack periodically checks DNS records for pending domains. Once all required records are detected, the domain is automatically verified. You can also trigger verification manually via the API or dashboard.

Auto-verification runs every 30 minutes for pending domains. For immediate verification, call the POST /domains/:id/verify endpoint after adding your DNS records.

Tracking Domains

Use a custom tracking domain for branded open/click tracking URLs instead of the default PostStack domain. Add a CNAME record pointing to track.poststack.dev and configure it on the domain:

typescript

await poststack.domains.update('dom_abc123def456', {
  tracking_domain: 'track.yourdomain.com',
});

// Links in emails will now use:
// https://track.yourdomain.com/c/... instead of
// https://track.poststack.dev/c/...

BIMI (Brand Indicators)

BIMI (Brand Indicators for Message Identification) displays your brand logo next to your emails in supported mail clients. Configure BIMI by providing your logo URL (must use HTTPS) and adding the required DNS TXT record:

typescript

await poststack.domains.update('dom_abc123def456', {
  bimi_logo_url: 'https://yourdomain.com/.well-known/bimi/logo.svg',
});

Add a BIMI TXT record to your DNS:

bash

Type:  TXT
Name:  default._bimi.yourdomain.com
Value: v=BIMI1; l=https://yourdomain.com/.well-known/bimi/logo.svg;

Inbound Email

Enable inbound email processing on a domain to receive and parse incoming emails. See the Inbound Email section for full details on setup and webhook configuration.

typescript

await poststack.domains.update('dom_abc123def456', {
  inbound_enabled: true,
});

Catch-All

Enable catch-all to receive emails sent to any address at your domain, even if no matching mailbox exists. Useful for ensuring you never miss an email:

typescript

await poststack.domains.update('dom_abc123def456', {
  catch_all: true,
});