API keys
The passwords your systems use to talk to Postal: create, limit and revoke.
What it's for
An API key is the password your system uses to talk to Postal, through the API (the Authorization: Bearer ps_... header) or over SMTP. This area creates, lists and revokes keys and shows what each one has been doing.
When to use: When integrating a new system, when giving restricted access to an app and when answering "who made this call?".
#List of keys
Where to find it: Developers › API keys. Address: app.postal.so/api-keys.
| Item | What it does |
|---|---|
| View code | Shows how to create a key through the API (POST /api-keys). |
| Create key | Opens the creation form (see below). With no domain on the team, the button becomes Add a domain: the key sends through the team's domains, and there are none yet. |
| Search by name or key prefix | Searches by the name or the first characters (ps_ab12). |
| Filters › Permission | Full access or Sending only. |
| Export | Generates a CSV of the keys (never with the token). |
| Column | What it shows |
|---|---|
| Name | The name you gave it (links to the details). |
| Key | Only the beginning (ps_ab12…), so you can recognize the key. The full token is never shown again. |
| Permission | Full access or Sending (with the domain name, when the key is restricted to one). |
| Uses | How many requests the key has made. |
| Last used | How long ago it was last used. A key that has not been used for months is a candidate for revoking. |
| Created on | When it was created. |
| Trash | Revoke ...: the applications that use the key stop working immediately. |
Below the table, a reminder that the same keys work as passwords for sending over SMTP, with the View SMTP credentials link.
Create a key
- Click Create key and give it a Name (up to 50 characters; tip: one name per system and per environment, like "Production" or "Store").
- Choose the Permission (see below) and, on sending-only keys, the Domain (optional) the key is restricted to.
- Click Create key. The Key created screen shows the token only once (Copy the key now. For security, it won't be shown again.), with a copy button. Store it in an environment variable and click Done.
See also: Authentication · API keys (API) · SMTP.
#Permissions and key details
Permissions
| Permission | What the key can do |
|---|---|
| Full access | Sends and reads emails, domains, keys, webhooks and the rest of the API. Keep it for infrastructure automations and your product's server. |
| Send only | Only sends emails (POST /emails, POST /emails/batch), events (POST /events) and SMTP; it can also look up the emails it sent itself and the plan and quotas in GET /usage. It does not read emails from other keys, domains, contacts or other keys. |
| Domain | On sending-only keys, All domains or one domain: then the key only sends with that domain's senders. |
Creating sending-only keys or keys restricted to a domain, and the number of keys, depend on the plan.
Tip
Use sending-only keys for everything that just fires off emails (checkout, WordPress, ERP) and one key per system: if one leaks, you revoke only that one without bringing down the rest, and the logs show who made each call.
Key details
Clicking a key opens its summary, with the Revoke button:
| Section | What it shows |
|---|---|
| Permission and Domain | What the key can do and which domain it is tied to (or All). |
| Total uses and Last used | The accumulated usage. |
| Created by and Created | Who created it and when. |
| Recent requests | The key's last 10 calls, with the See all link to the Logs already filtered by it. With no calls, it shows No requests recorded with this key. |
Warning
Revoking a key is immediate and cannot be undone. Replace the key in the systems that use it before revoking the old one: create the new one, update the system and only then revoke.
See also: Permissions (API) · API keys (API).