Get a DNS API token (automatic setup)
Instead of adding every record by hand (manual DNS guide), you can give WisMail a DNS API token. In Status, Setup & Health the automatic DNS setup uses it to create the missing records (A, MX, SPF, DKIM, DMARC) at your DNS provider and then re-checks them. This guide shows how to create a token that can do only that. Allow about 5 minutes.
What the token is for
- Server host name (administrator). The administrator of the server uses the token so the server's own name, for example
mail.example.com, gets its A record and the mail records of the primary domain. - A customer adding a domain or subdomain. A customer who adds their own domain (or a subdomain such as
mail.customer.com) creates a token for that one zone and WisMail publishes the records for it.
The token is not your DNS account password, and it cannot sign in to your DNS provider.
Keep it least-privilege
Create the token with only the permission to edit DNS records, limited to the one zone (domain) you are setting up. Do not use a global API key and do not give access to all zones, billing or account settings. A leaked token with that scope can change DNS records of one domain and nothing else, and you can delete it at any time.
Two ways to use the token
| Mode | What happens | Choose it when |
|---|---|---|
| One-time | WisMail uses the token for this setup run only and does not keep it. Delete the token at your DNS provider afterwards. | You only need the first setup. |
| Stored, encrypted | WisMail keeps the token encrypted on the server so it can fix records later, for example if one disappears or the DKIM key changes. You can remove it at any time. | You want ongoing auto-fix. |
If you are unsure, start with one-time. You can create another token later.
Cloudflare
Cloudflare is the most common DNS host, so the steps come first. The dashboard changes from time to time; the official page is the source of truth: Create API token (Cloudflare documentation).
- Sign in at
dash.cloudflare.com. - Open the profile menu at the top right, choose My Profile, then API Tokens.
- Click Create Token.
- Next to the Edit zone DNS template click Use template.
- Name the token, for example
wismail-dns. - Under Permissions keep exactly one line: Zone, DNS, Edit.
- Under Zone Resources choose Include, Specific zone and select the one domain you are setting up. Do not choose All zones.
- Optional: set a TTL (end date) for the token so it expires by itself.
- Click Continue to summary, check that it says DNS edit on that one zone, then Create Token.
- Copy the token now. Cloudflare shows it only once. Paste it into the WisMail setup screen.
- If you chose one-time mode, return to My Profile, API Tokens after the setup and delete the token (Roll or Delete).
To test the token before using it:
curl -s https://api.cloudflare.com/client/v4/user/tokens/verify -H "Authorization: Bearer YOUR_TOKEN"
A valid token answers with "status":"active".
Other providers (short outline)
The principle is the same: a token or key that can edit DNS records for one zone only. Detailed steps for these providers will be added; until then follow the provider's own documentation and use the manual guide if a provider cannot scope a token.
- DigitalOcean. Control Panel, API, Tokens, generate a token with a custom scope limited to domain records (read and write); see the DigitalOcean guide to personal access tokens.
- Vultr. Account, API: Vultr keys cannot be limited to one domain, so restrict the key to the server IP address in the access control list and delete it after a one-time run.
- AWS Route 53. Create an IAM user or role with a policy that allows
route53:ChangeResourceRecordSetsandroute53:ListResourceRecordSetson the ARN of the one hosted zone, plusroute53:ListHostedZones; use its access key pair. - Namecheap. Profile, Tools, API Access: the key covers the whole account and needs the server IP on the allowed list. If you prefer least-privilege, use the manual DNS guide.
If something fails
- Token rejected. Copy it again without spaces, and check that it is not expired and that the zone matches the domain.
- Records not created. The token lacks DNS edit on that zone, or the domain's name servers are at another provider.
- Created but still red in Setup & Health. DNS needs time to propagate; press Re-run all checks after a few minutes. PTR is not part of this: it is set at your VPS or IP provider (manual DNS guide).
Next steps
- Set up DNS for your email by hand: every record explained.
- Install guide if the server is not set up yet.
- Set up SSL/TLS once the host name resolves.
- Pricing or the free trial.