Authentication

API keys#

Send your key as a Bearer token on every request to https://api.poststack.dev. Keys look like sk_live_ or sk_test_ followed by 64 hex characters.

import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack(process.env.POSTSTACK_API_KEY!);

curl https://api.poststack.dev/emails \
  -H "Authorization: Bearer $POSTSTACK_API_KEY"

import os
from poststack import PostStack

ps = PostStack(api_key=os.environ["POSTSTACK_API_KEY"])

client := poststack.NewClient(os.Getenv("POSTSTACK_API_KEY"))

A missing or wrong key on a GET returns 401 with a WWW-Authenticate: Bearer header. On POST, PATCH, PUT and DELETE, a request with no Authorization: Bearer header is treated as a browser request and refused with 403 Invalid request origin before the key is even looked at. The scheme is case-sensitive: write Bearer.

Create a key#

1. Open API keys

   In the dashboard, go to Configuration → API keys and choose Create API key. Your email address must be verified first.

2. Choose what the key may do

   Give it a Name, a Permission (Full access or Sending only), a Mode (Live or Test) and, optionally, a domain under Restrict to domain.

3. Copy the key

   The full key is shown once. PostStack stores only a hash, so a lost key cannot be recovered — rotate it to get a new one.

How many keys a team can hold depends on the plan: 5 on Free, 10 on Starter, 50 on Pro, 1,000 on Scale and unlimited on Enterprise.

Permissions#

A sending-only key calling anything else gets 403 { "error": "insufficient_scope", "required": [...], "missing": [...] }. Use sending-only keys in application servers that just send mail; keep full-access keys for setup scripts and infrastructure tools.

Domain-restricted keys#

A key restricted to one domain can only send from addresses on that domain. Any other from is refused with 403 API key is restricted to a different domain. Without a restriction a key may send from every domain on the team.

One restricted key per customer or per app is the safest setup: a leaked key can only ever send as its own domain, which keeps many domains under one account isolated from each other. Deleting a domain expires the keys restricted to it immediately, so a restricted key never silently becomes an unrestricted one.

Test keys#

A key created in Test mode starts with sk_test_. It runs every check a live key does but never delivers anything, and its sends do not count against your plan. See Test mode.

OAuth access tokens#

Third-party integrations do not handle your API keys: you authorise them through PostStack's OAuth flow and they receive an access token starting with pat_, sent the same way (Authorization: Bearer pat_…). A token can only do what its scopes allow — for example email:send, domains:read or contacts:manage — and an endpoint outside them returns 403 insufficient_scope. An expired or revoked token returns 401 Invalid or expired access token.

Managing keys over the API#

These endpoints need a full-access key, a dashboard session, or an OAuth token with api-keys:manage. Reading the key list is also open to sending-only keys.

{
  "name": "Production app server",
  "permission": "sending_access",
  "mode": "live",
  "domain_id": "dom_8k2m4q7x1c5w9r3t6z0p2n4v"
}

HTTP/1.1 201 Created

{
  "key": "sk_live_3f9a2c7e1b8d4f6a0c9e5b2d7f1a3c8e6b4d9f2a7c1e5b8d3f6a0c9e2b7d4f1a",
  "id": 214,
  "name": "Production app server",
  "permission": "sending_access",
  "mode": "live",
  "keyPrefix": "sk_live_3f9a"
}

const { key, id } = await poststack.apiKeys.create({
  name: 'Production app server',
  permission: 'sending_access',
  domain_id: 'dom_8k2m4q7x1c5w9r3t6z0p2n4v',
});

curl -X POST https://api.poststack.dev/api-keys \
  -H "Authorization: Bearer $POSTSTACK_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production app server", "permission": "sending_access" }'

{
  "keys": [
    {
      "id": 214,
      "name": "Production app server",
      "keyPrefix": "sk_live_3f9a",
      "permission": "sending_access",
      "mode": "live",
      "domainId": 41,
      "domainName": "acme.com",
      "lastUsedAt": "2026-09-29T09:58:12.004Z",
      "expiresAt": null,
      "createdAt": "2026-08-14T12:00:00.000Z"
    }
  ]
}

const { keys } = await poststack.apiKeys.list();

curl https://api.poststack.dev/api-keys \
  -H "Authorization: Bearer $POSTSTACK_API_KEY"

{
  "id": 214,
  "name": "Production app server",
  "keyPrefix": "sk_live_3f9a",
  "permission": "sending_access",
  "mode": "live",
  "domainId": 41,
  "lastUsedAt": "2026-09-29T09:58:12.004Z",
  "expiresAt": null,
  "createdAt": "2026-08-14T12:00:00.000Z"
}

const key = await poststack.apiKeys.get(214);

curl https://api.poststack.dev/api-keys/214 \
  -H "Authorization: Bearer $POSTSTACK_API_KEY"

HTTP/1.1 201 Created

{
  "key": "sk_live_9c1e4b7d2f8a5c3e0b6d9f1a4c7e2b8d5f0a3c6e9b1d4f7a2c5e8b0d3f6a9c1e",
  "id": 231,
  "name": "Production app server",
  "permission": "sending_access",
  "mode": "live",
  "keyPrefix": "sk_live_9c1e"
}

const { key } = await poststack.apiKeys.rotate(214);

curl -X POST https://api.poststack.dev/api-keys/214/rotate \
  -H "Authorization: Bearer $POSTSTACK_ADMIN_KEY"

{
  "success": true
}

await poststack.apiKeys.revoke(214);

curl -X DELETE https://api.poststack.dev/api-keys/214 \
  -H "Authorization: Bearer $POSTSTACK_ADMIN_KEY"

SMTP credentials#

The SMTP relay authenticates with the same keys:

Troubleshooting#

Next steps