Skip to main content
The Drin REST API. Every endpoint is versioned under /v1, speaks JSON, and authenticates with a bearer key. The same surface is mirrored by the SDK, the CLI, and the MCP server. The base URL is https://api.drin.run. Authenticate every request with your API key in the Authorization header. You can run your first POST /v1/emails the moment you have a key — no DNS required in test mode.
Base URL
curl https://api.drin.run/v1/emails \
  -H "Authorization: Bearer $DRIN_API_KEY"

​
Conventions

Requests and responses are JSON. Send Content-Type: application/json on any request with a body. Field names are camelCase; timestamps are ISO 8601 (2026-06-02T17:04:00Z); identifiers are opaque strings — treat them as such and never parse them.

Authentication

Authorization: Bearer <key>, plus X-Drin-Product to name a project for account-wide keys.

Errors

A consistent { "error": { "type", "message" } } envelope on every non-2xx response.

Pagination

Cursor pages: ?limit, ?cursor, nextCursor.

Rate limits

429 with a Retry-After header when you go too fast.

​
Versioning

Every path is prefixed with /v1. We add fields and endpoints without bumping the version — new optional response fields and new query parameters are not breaking changes, so write your client to ignore unknown fields. A breaking change would ship under a new version prefix.

​
Pagination

List endpoints return a cursor page. Pass ?limit (1–100) and ?cursor (the previous response’s nextCursor). When nextCursor is null, you’ve reached the end.
Page shape
{
  "data": [ /* … */ ],
  "nextCursor": "eyJpZCI6Im1zZ18wMUgifQ"
}
The SDK and CLI auto-paginate. See Pagination for the full walk.

​
Idempotency

Send an Idempotency-Key header on a POST to make it safe to retry — the same key replays the original result for 24 hours, per project, so a retried send never duplicates. See Idempotency & retries.

​
Status codes

Drin uses conventional HTTP status codes.
CodeMeaning
200 / 201Success. The body holds the resource you asked for.
202Accepted — the send was queued. Returns a message id and a status.
204Success, no body (for example, a delete).
207Multi-status — a batch where items can each succeed or fail.
4xxYour request. See Errors.
5xxOur side. Safe to retry idempotently.
Request IDs. Every response echoes an X-Request-Id header. Include it when you contact support — it lets us find the exact request in our logs.

Send your first request

The quickstart walks through a real POST /v1/emails end to end.