Authentication

API keys

An API key has two parts, and the distinction matters:

• The key ID (key_a1b2c3d4-e5f6-7890-abcd-ef1234567890) names the key. It appears in the dashboard and in API paths like /v1/api-keys/{id}. It is not a secret.
• The secret (ap_AbCdEf12KxLmNoPq...) authenticates your requests. Treat it like a password.

The secret is returned once, in the response to the request that creates the key. Anypost stores only a hash of it and cannot show it again. If you lose it, create a new key.

Each key also has a prefix: the first 12 characters of the secret, such as ap_AbCdEf12Kx. Lists of keys show the prefix so you can tell them apart without exposing the full secret.

Authenticating requests

Over the HTTP API, send the secret as a bearer token:

curl https://api.anypost.com/v1/email \
  -H "Authorization: Bearer ap_AbCdEf12KxLmNoPq..." \
  -H "Content-Type: application/json" \
  -d '{ "from": "[email protected]", "to": ["[email protected]"],
        "subject": "Hello", "text": "Hello, inbox!" }'

Over SMTP, authenticate with a fixed username and the secret as the password:

SMTP host, ports, and TLS settings are covered in Sending over SMTP.

Permissions

Every key has one permission level, set when you create it and changeable later:

Give an application server that only sends mail a send_only key. It limits what an attacker can do if the key leaks.

Restricting a key

Two optional restrictions narrow where a key can be used. Both default to unrestricted.

• allowed_domains: the sending domains a key may use in the from address. When set, a send from any other domain is rejected. Unset means all of your team's verified domains.
• allowed_ips: the IP addresses or CIDR blocks that may present the key. A request from any other address returns 403. Unset means any IP.

Creating and managing keys

Manage keys in the dashboard, or through the /v1/api-keys endpoints: POST to create, GET to list, PATCH to update, DELETE to remove. Creating a key over the API requires an existing full key, so your first key comes from the dashboard.

The full secret (key) is on the create response only. Store it then, as it cannot be retrieved later:

curl https://api.anypost.com/v1/api-keys \
  -H "Authorization: Bearer $ANYPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production server",
    "permissions": "send_only"
  }'

PATCH changes a key's name, permission level, and restrictions. It never changes the secret.

Each key records when it was last used, which helps identify keys that are safe to delete. Changes to a key, including deletion, propagate within about 5 minutes; a deleted or downgraded key may keep working until then.

Rotating a key

There is no rotate operation for API keys. To rotate one:

1. Create a new key with the same permissions and restrictions.
2. Deploy it everywhere the old key is used.
3. Delete the old key.

Running both keys during the cutover avoids downtime.

When authentication fails

Repeated failed attempts from one IP are temporarily blocked. Fix the credential rather than retrying.

Where to go next

• Domains & DNS setup: verify a domain before you can send from it.
• Sending over SMTP: host, ports, and TLS for the SMTP transport.
• Send a single email: the full POST /v1/email request.