Authentication

Every request to the Emailgistics API is authenticated with a Bearer API key. The key goes in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The same key system also issues the secret used for webhook delivery.

What a key is bound to

Each key has four properties, set when the key is created and immutable thereafter:

Name — a human-readable label for your own tracking.
Expiry date — the key stops working at this date. Shorter expiries are more secure.
Mailbox allowlist — the key authorizes calls only against these mailboxes. Calls targeting a mailbox outside the list return 404 (we don’t distinguish “doesn’t exist” from “exists but you’re not authorized for it”).
Scopes — the set of operations the key can perform. See Scopes.

Generating a key

Open the API Access page from the menu.

Click Add Key, then enter a name, expiry date, the mailboxes the key may access, and the scopes the key needs.

Click Generate Key and copy the key out of the dialog.

The full key value is shown only at the moment of generation. After you leave the page, only a truncated identifier is visible. Copy the key immediately and store it in a secret manager — there is no way to retrieve it later.

Storing and rotating keys

Treat the key like a password. Don’t commit it to source control, log it, or send it in plain text email.
Inject it into your runtime via an environment variable or a secrets manager.
Rotate keys periodically by generating a new one, updating callers to use it, and revoking the old one once cutover is complete.

Revoking a key

Delete the key from the API Access page. Calls using a deleted key immediately return 401.

Errors

Status	Cause
`401`	Header missing, key malformed, or key expired/revoked.
`403`	Key is missing a required scope.
`404`	The targeted mailbox is not in the key’s allowlist (or doesn’t exist — the two cases are indistinguishable).