# Create and revoke send API keys

> Create an API key that sends mail through SMTP Relay over HTTPS, keep its secret safe, and revoke it when you no longer need it.

Source: https://docs.coritan.com/mail/smtp-relay/api-keys/

In the dashboard:

- /dashboard/mail/…/api-keys: https://www.coritan.com/dashboard/mail

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](/mail/smtp-relay/send-with-the-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](/account/api-keys/). To manage the relay itself from code, use an access token, as [Make your first API request](/get-started/first-steps-with-the-api/) shows.

## Before you begin

- 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](/mail/smtp-relay/credentials/) 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.`

## Create a key

1. In the dashboard, go to [**Email**](https://www.coritan.com/dashboard/mail), 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.

## Result

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](/mail/smtp-relay/send-with-the-api/) explains every field.

## Revoke a key

> [!CAUTION]
> Revoking a key cannot be undone. We refuse requests with the key from then on, so replace it in every application that uses it first.

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.

## Troubleshooting

**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.

## Related

- [Send email over HTTPS](/mail/smtp-relay/send-with-the-api/)
- [Send over SMTP with credentials](/mail/smtp-relay/credentials/)
- [How SMTP Relay sending limits work](/mail/smtp-relay/sending-limits/)

## With the API

Create a key:

```bash
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:

```json
{
  "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:

| Operation | Answer |
| --- | --- |
| `GET /client/smtp-relay/{service_id}/api-keys` | `{"items": [...]}`: every key that is not revoked, as above without `key` |
| `DELETE /client/smtp-relay/{service_id}/api-keys/{key_id}` | `{"ok": true}`. The key stops working at once. |

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.

### On a Mail Hosting service

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

## API

- `GET /api/v1/client/smtp-relay/{service_id}/api-keys`: List API keys (https://docs.coritan.com/api/reference/client/mail/smtp-relay-api-keys/#op-get-api-v1-client-smtp-relay-service-id-api-keys)
- `POST /api/v1/client/smtp-relay/{service_id}/api-keys`: Create API key (https://docs.coritan.com/api/reference/client/mail/smtp-relay-api-keys/#op-post-api-v1-client-smtp-relay-service-id-api-keys)
- `DELETE /api/v1/client/smtp-relay/{service_id}/api-keys/{key_id}`: Revoke API key (https://docs.coritan.com/api/reference/client/mail/smtp-relay-api-keys/#op-delete-api-v1-client-smtp-relay-service-id-api-keys-key-id)
- `GET /api/v1/client/mail/{service_id}/api-keys`: List API keys (https://docs.coritan.com/api/reference/client/mail/mail-api-keys/#op-get-api-v1-client-mail-service-id-api-keys)
- `POST /api/v1/client/mail/{service_id}/api-keys`: Create API key (https://docs.coritan.com/api/reference/client/mail/mail-api-keys/#op-post-api-v1-client-mail-service-id-api-keys)
- `DELETE /api/v1/client/mail/{service_id}/api-keys/{key_id}`: Revoke API key (https://docs.coritan.com/api/reference/client/mail/mail-api-keys/#op-delete-api-v1-client-mail-service-id-api-keys-key-id)