Create and revoke send API keys

A send API key lets an application send mail through SMTP Relay over HTTPS instead of SMTP. The application puts the key in the X-Api-Key header of each request to the send API. A key can only send, and only through the relay that made it: it cannot read or change the service.

These keys are separate from the keys on the API keys tab of Settings, which are described in Manage API keys. To manage the relay itself from code, use an access token, as Make your first API request shows.

• An SMTP Relay service with the status active. While it is not, Create API key… is greyed out.
• A verified sending domain and at least one SMTP credential on the relay. You can create a key without them, but the send API refuses to send until both exist.
• Fewer than 20 keys on the relay. The API keys card shows how many you have, such as 3 of 20 keys.

1. In the dashboard, go to Email, open the SMTP Relay service, then the API keys tab.
2. Select Create API key….
3. In Label, name the application that will hold the key, such as billing service. Leave it empty and the label is default.
4. Select Create API key.
5. Copy the API key from the dialog and store it where the application keeps its secrets. We show the key only this once.
6. Select I have saved them.

A key looks like mk_5e0c9a7b_ followed by 43 more characters. The first part, such as mk_5e0c9a7b, is its prefix. We keep the prefix so that you can tell keys apart, and we cannot show the rest of the key again.

Keep the key on your server. Anyone who has it can send mail from your domains until you revoke it, so do not put it in a web page, a mobile app or a public repository.

The key is listed on the API keys tab with its label, its prefix, its Abilities (send), when it was Last used (Never until its first request) and when it was Created.

The Send over HTTPS card below the list holds two requests to copy, Send a message and Your limits, with one of your domains in the From address. Replace mk_... with the key and run them. Send email over HTTPS explains every field.

1. On the API keys tab, select Revoke… in the key's row.
2. Type the key's prefix, such as mk_5e0c9a7b, to confirm, then select Revoke key.

The key leaves the list, and a toast confirms it, such as Key "billing service" revoked. To give an application access again, create a new key.

To replace a key without stopping the application, create the new key, put it in the application, check that its Last used time moves, then revoke the old one.

Create API key… is greyed out

The relay is not active, or it already has 20 keys and the API keys card shows 20 of 20 keys. Revoke a key you no longer use.

Revoke an unused API key first (limit 20)

The relay already has 20 keys. Revoked keys do not count, so revoke one you no longer use.

401 Invalid API key

The key is mistyped, cut short or revoked, or the relay is not active. Check the whole key, including the mk_ at the start. If you no longer have it, create a new key.

401 X-Api-Key header required

The request has no X-Api-Key header. Send the key in that header: the send API does not read Authorization.

You lost a key

We cannot show a key again. Create a new one, put it in the application, and revoke the old one.

• Send email over HTTPS
• Send over SMTP with credentials
• How SMTP Relay sending limits work

Create a key:

curl -X POST https://api.coritan.com/api/v1/client/smtp-relay/4812/api-keys \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "billing service"}'

label is optional, 1–100 characters, and default when left out. The answer is 201 with the key in key, shown this once:

{
  "id": 88,
  "label": "billing service",
  "key_prefix": "mk_5e0c9a7b",
  "abilities": ["send"],
  "last_used_at": null,
  "revoked_at": null,
  "created_at": "2026-09-16T10:52:03.418207+00:00",
  "key": "mk_5e0c9a7b_Q2hSbE9wN3ZrTjRaWnFMY1d4dUJ5ZzFSbTZUaEg4ZXM"
}

The other operations:

A key id that is not on the relay answers 404 Not found, and a relay with 20 keys answers 400 Revoke an unused API key first (limit 20). The API creates a key while the relay is not active, but the key answers 401 until the relay is active again.

Mail Hosting has no send API. Every path under /client/mail/{service_id}/api-keys answers 404 Not an SMTP Relay service.