API reference

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.

curl https://api.drin.run/v1/emails \
  -H "Authorization: Bearer $DRIN_API_KEY"

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

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

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

{
  "data": [ /* … */ ],
  "nextCursor": "eyJpZCI6Im1zZ18wMUgifQ"
}

The SDK and CLI auto-paginate. See Pagination for the full walk.

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

05 Status codes

Drin uses conventional HTTP status codes.