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": "us-east-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

{
  "id": "dom_abc123def456",
  "name": "yourdomain.com",
  "status": "verified",
  "region": "eu-west-1",
  "tls_mode": "enforced",
  "open_tracking": true,
  "click_tracking": true,
  "catch_all": false,
  "dns_records": [
    {
      "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

{
  "deleted": true
}

POST

/domains/:id/verify

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

json

{
  "id": "dom_abc123def456",
  "name": "yourdomain.com",
  "status": "verified",
  "dns_records": [
    {
      "purpose": "spf",
      "verified": true
    },
    {
      "purpose": "dkim",
      "verified": true
    },
    {
      "purpose": "dmarc",
      "verified": true
    }
  ]
}

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": {
    "total": 15,
    "page": 1,
    "per_page": 20,
    "total_pages": 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

Choose the sending region when creating a domain to optimize email delivery for your recipients:

Region	Location
`eu-west-1`	Europe (Ireland)
`us-east-1`	US East (Virginia)
`sa-east-1`	South America (Sao Paulo)
`ap-northeast-1`	Asia Pacific (Tokyo)

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,
});