Authentication

Bearer API keys, project scoping, and idempotent requests.

Every request authenticates with an API key sent as a Bearer token:

Authorization: Bearer $DRIN_API_KEY

Create and revoke keys in the dashboard under API Keys, or over the API (POST /v1/api-keys). The secret is shown once at creation — store it immediately; you can’t read it back.

API keys are secrets. Use them only from server-side code, never in a browser, mobile app, or anything shipped to a user. If a key leaks, revoke it and mint a new one.

Choosing the sending project

A Drin account can hold several projects (each its own sender identity, domains, and keys). Two kinds of key decide how the project is chosen:

Project-scoped key

Tied to one project. The project is implied — send with just the Authorization header, nothing else.

Account-wide key

Spans every project. You must name the project per request so Drin knows who’s sending.

Name the project on an account-wide key with the X-Drin-Product header:

Authorization: Bearer $DRIN_API_KEY
X-Drin-Product: my-project        # the project's external id

X-Drin-Product is the canonical header. X-Drin-Sender is an accepted alias (it’s what the SDK’s sender option, the CLI’s --sender flag, and the DRIN_SENDER env var send). All three name the same thing.

In the SDK, pass sender once when you construct the client:

const drin = new DrinClient({
  apiKey: process.env.DRIN_API_KEY,
  sender: "my-project", // only needed for account-wide keys
});

Request headers

Header	Required	Purpose
Authorization	Always	Bearer <api-key>.
Content-Type	On POST/PATCH	application/json.
X-Drin-Product	Account-wide keys	Names the sending project (alias: X-Drin-Sender).
Idempotency-Key	Optional	Safe-retry a POST (see below).

Idempotency

Pass an Idempotency-Key on any POST to make it safe to retry — if the same key arrives twice, Drin returns the original result instead of sending again. Keys are honored for 24 hours, per sending project.

cURL

curl https://api.drin.run/v1/emails \
  -H "Authorization: Bearer $DRIN_API_KEY" \
  -H "Idempotency-Key: order-1234-receipt" \
  -H "Content-Type: application/json" \
  -d '{ "from": {"email":"[e-mail]"}, "to":[{"email":"[e-mail]"}], "subject":"Receipt", "html":"<p>Thanks!</p>" }'

The SDK automatically retries transient failures (429 and 5xx) with exponential backoff — and it only retries a POST when you’ve supplied an Idempotency-Key, so a send is never duplicated.