Authentication

Every request authenticates with an API key sent as a Bearer token. Account-wide keys name the sending project per request; project-scoped keys don’t. Send the key in the Authorization header:

Authorization

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.

Keep keys server-side. 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 with 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:

Headers

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

Header aliases. 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:

Node.js

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 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": "hi@acme.com" },
    "to": [{ "email": "a@b.com" }],
    "subject": "Receipt",
    "html": "<p>Thanks!</p>"
  }'

await drin.emails.send(
  {
    from: { email: "hi@acme.com" },
    to: [{ email: "a@b.com" }],
    subject: "Receipt",
    html: "<p>Thanks!</p>",
  },
  { idempotencyKey: "order-1234-receipt" },
);

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. See Errors for the full retry behaviour.

​Choosing the sending project

Project-scoped key

Account-wide key

​Request headers

​Idempotency

Choosing the sending project

Request headers

Idempotency