White-label API

If you resell sending — an agency running mail for its clients, or a SaaS with its own “connect your domain” screen — your backend can drive Postwing directly: create domains, read the DNS records your users have to publish, issue SMTP credentials and register webhooks, all from your own product. Your users never see this panel and never hear the name Postwing.

That is what a white-label token buys. It is an account-level API credential, issued from the dashboard, that authenticates against a separate machine API under /api/wl/v1/.

What you need

White-label is an account-level entitlement. It is not part of a plan and there is nothing to buy — we switch it on for your account when you ask us to. Until then the White-label page in your account settings tells you how to get in touch; afterwards it lists your tokens. The entitlement covers the whole account, so a token is not tied to any one of your domains.

Your hostnames in your customers' DNS, not ours

This is the part that makes the feature worth having, and it is a separate setting from the token. Out of the box, the records we generate for a domain name us in three places — the places your customer copies into their own DNS panel and reads every time they audit their zone:

One field replaces all three. In Account → White-label, set your own DNS domain — a domain you own, e.g. mail.reseller.com. From then on, domains you create through the API generate include:spf.mail.reseller.com, a CNAME to stats.mail.reseller.com and rua=mailto:dmarc@dmarc.mail.reseller.com. Nothing in your customer's zone says Postwing.

The setting belongs to the storefront you configure it on, not to your account as a whole. If you also sell through another of our storefronts, that one carries its own DNS domain and its own set of records — the hosts they have to point at are different, so a single zone cannot be correct for both. Configure each one where you sell.

The same field is writable over the API — as a dashboard credential, not a white-label token:

curl -X PATCH https://api.postwing.app/api/whitelabel/settings/ \
  -H "Authorization: Bearer $YOUR_DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{"dns_domain": "mail.reseller.com"}'

Deliberately so. A leaked machine credential must not be able to repoint every future customer's DNS, which is why this one route stays on the panel with the token issuing and revoking.

What you publish, once

The labels spf., stats., dmarc. and mx. are fixed; you supply the domain part. In your zone you publish five records, one time — not per customer:

The SPF row is the one to read carefully: what belongs at spf.mail.reseller.com is a policy that includes spf.postwing.app, and a CNAME is the simplest way to publish it because it then keeps itself up to date as our sending IPs change. A TXT policy of your own works too, as long as it authorises us. Do not read the value the API reports for this record — v=spf1 — as a string to paste: it is the marker we compare against, and published on its own it authorises nobody. v=DMARC1 on the wildcard, by contrast, is the whole record.

The middle pair is for DMARC reports. Your customers' aggregate reports are addressed to a mailbox in your domain, so the MX has to reach us and — because the domain being reported on is your customer's and the mailbox is yours — RFC 7489 §7.1 makes a receiver look for permission before sending. That permission is one wildcard, not a record per customer. The White-label page resolves all five, shows each one's state and tells you what is missing; press Check after publishing.

Issuing a token

1. Go to Account → White-label in the dashboard.
2. Click Issue token, give it a name, optionally an expiry, and pick its scopes.
3. Copy the secret. It looks like wl_ followed by 48 characters and it is displayed exactly once — it is stored hashed and cannot be recovered. If you lose it, revoke the token and issue a new one.

The list afterwards shows a masked form (wl_ab12cd34…) so you can tell two tokens apart, plus when each was last used. Tokens cannot be edited: to change a token's scopes or expiry, issue a new one and revoke the old. Revoking takes effect immediately — anything still using that credential starts failing at once.

Authentication

Send the secret as a bearer token on every request:

curl https://api.postwing.app/api/wl/v1/domains/ \
  -H "Authorization: Bearer wl_your-token-here"

A white-label token authenticates only against /api/wl/v1/. It cannot read your profile, your billing, or mint another token — the rest of the API does not know how to authenticate it and answers 401.

Rate limit: 120 requests per minute, per token. The bucket is per token, not per account, so separate integrations don't compete for the same budget. Over the limit you get 429.

Scopes

Read and write are split, so an integration that only mirrors state into your own UI can hold a credential that cannot create or delete anything.

A token issued without narrowing gets all eight — the common case is one backend running the whole onboarding flow. A request outside its token's scopes is refused with a 403 naming the scope it needed:

{
    "detail": "This token is missing the \"domains:write\" scope"
}

Endpoints

Base URL https://api.postwing.app/api/wl/v1/. Everything is addressed by uuid, including the ?domain= filter. The version is in the path from the first release, so a future /v2/ will not move your integration out from under you.

Billing for domains you create

A domain created through POST /api/wl/v1/domains/ lands on a dedicated white-label plan that is never billed: no invoices, no payment reminders, no plan checkout, nothing for your customer or for you to pay per domain. Their sending limits are set by us per customer as part of your white-label arrangement — talk to us if you need them raised.

A domain's own plan still applies

White-label changes who is calling, never what a domain's plan includes. Every other feature gate is untouched: registering a webhook endpoint on a domain whose own plan does not include webhooks is still a 403, exactly as it would be in the dashboard. The same goes for templates, analytics and exports.

Domain webhook events

Two event types exist for the domain lifecycle, on top of the message events. They are opt-in: put them in an endpoint's events array (via the API above, or the Webhooks screen in the dashboard). Existing endpoints are not changed.

A re-check that changes nothing emits nothing, so a domain that is already verified does not produce a webhook every time the sweep runs.

{
    "event_id": "5d1f7ce0-6f0f-4d09-9f27-3fd06d6fa1a1",
    "event": "domain.verified",
    "domain": "mail.customer.example",
    "domain_id": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
    "timestamp": "2026-08-03T09:41:07.512340+00:00",
    "data": { "verified_at": "2026-08-03T09:41:07.480112+00:00" }
}

Worked example

The normal onboarding flow, end to end. The order is not just a suggestion: SMTP credentials cannot be issued for a domain that has not verified yet, so a provisioning job that tries to hand back a username and password in the same call that creates the domain will always fail.

1. Create the domain

curl -X POST https://api.postwing.app/api/wl/v1/domains/ \
  -H "Authorization: Bearer $WL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.customer.example"}'

The 201 is the domain itself — its uuid, its plan, its verification state. It does not contain the DNS records; keep the uuid and ask for them next.

{
    "uuid": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
    "domain": "mail.customer.example",
    "verified_at": null,
    "last_check_at": null,
    "dns_error_at": null,
    "plan": {
        "uuid": "c4a1e0d6-9b52-4f8e-83a1-7c5d0e2f9b41",
        "name": "White label",
        "price": "0.00",
        "on_request": true,
        "webhooks_enabled": true,
        "inbound_enabled": true,
        "max_inbound_routes": 25
    },
    "created_at": "2026-08-03T09:40:12.884210+00:00"
}

2. Read the records to publish

A plain array, not a paginated envelope. Show them in your own UI, and poll this to render each record's current state — verified_at is set once that record checks out, checked_at is when it was last looked at, and last_result says why in the cases where it did not.

curl https://api.postwing.app/api/wl/v1/domains/0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22/records/ \
  -H "Authorization: Bearer $WL_TOKEN"

[
    {
        "uuid": "b81c6f4a-1e77-4d2e-9a55-6f0d1c3b7e90",
        "domain": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
        "type": "TXT",
        "name": "@",
        "full_name": "mail.customer.example",
        "value": "v=spf1 a mx include:spf.mail.reseller.com ~all",
        "match": "spf",
        "required": true,
        "verified_at": null,
        "checked_at": null,
        "last_result": null
    },
    {
        "uuid": "3a0e9d21-55b8-4c07-8f13-9d2b6a4e1c58",
        "domain": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
        "type": "TXT",
        "name": "default._domainkey",
        "full_name": "default._domainkey.mail.customer.example",
        "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhki...",
        "match": "exact",
        "required": true,
        "verified_at": null,
        "checked_at": null,
        "last_result": null
    }
]

match is the field to build your setup screen around. It says how DNS's answer is compared with value, and the two cases need different instructions to your customer:

A screen that treats every row as "publish exactly this" will tell a correctly configured customer their zone is broken, which is the support ticket this field exists to prevent.

3. Publish them, then verify

Once your user has added the records at their DNS provider, ask for a check immediately rather than waiting for the periodic sweep:

curl -X POST https://api.postwing.app/api/wl/v1/domains/0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22/verify/ \
  -H "Authorization: Bearer $WL_TOKEN"

4. Issue SMTP credentials

Verify the domain first. A credential can only be issued for a domain that has already passed its DNS check — call it before verified_at is set and it refuses with 400. That is what dictates the order above: create the domain, hand your customer the records, verify, then issue.

curl -X POST https://api.postwing.app/api/wl/v1/smtp-tokens/ \
  -H "Authorization: Bearer $WL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
    "username": "app",
    "note": "customer app"
  }'

{
    "id": 4711,
    "uuid": "7b1a4c2e-8f30-4f5b-9d61-0c4e2a7b8d33",
    "domain": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
    "username": "app@mail.customer.example",
    "note": "customer app",
    "_password": "generated-password-shown-once"
}

username is required, and it is a local part, not an address — we append @<domain> ourselves. Send app and the credential logs in as app@mail.customer.example; send app@mail.customer.example and you get the domain twice over. Keep it to letters, digits, underscores and hyphens, as the panel does. note is optional and is for you — it is what tells your support team which of a customer's integrations a credential belongs to. There is no password to choose: one is generated for you.

_password is returned in this response and nowhere else — store it as you would any other secret. Listing or retrieving a credential afterwards carries no password field at all, in any form: if you lose it, delete the credential and issue another. Use the pair against smtp.postwing.app exactly as described in Send over SMTP, and your customer's mail is flowing.

5. Subscribe to events

curl -X POST https://api.postwing.app/api/wl/v1/webhooks/ \
  -H "Authorization: Bearer $WL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
    "url": "https://your-app.example.com/hooks/postwing",
    "events": ["delivered", "bounced", "domain.verified"],
    "description": "customer 4711"
  }'

Signing, retries and delivery semantics are identical to the ordinary webhooks — see Webhooks for the signature scheme and the retry schedule.

6. Optional: let them receive

curl -X PUT https://api.postwing.app/api/wl/v1/domains/0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22/inbound/ \
  -H "Authorization: Bearer $WL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "inbound.mail.customer.example"}'

mx_target in the response is the value your customer publishes an MX at — and for a white-label domain it is a name under your DNS domain, so never build that string yourself. The MX record then appears in that domain's /records/ alongside the rest, and routes can be created:

curl -X POST https://api.postwing.app/api/wl/v1/inbound-routes/ \
  -H "Authorization: Bearer $WL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "0e0f3b6f-3d9e-4a8a-9c65-2b9a5b3f1f22",
    "pattern": "support",
    "endpoint": "9f2c1b7e-4d38-4a10-8b6c-5e0a3d7f2c19"
  }'

Matched mail arrives at your endpoint as an inbound.received webhook. Patterns, plus-tag matching and the payload are covered in Receiving email.