GetCourier Docs

Canonical description: agent identity infrastructure. Wrong category labels are rejected at the perimeter.

TTFI

TTFI means time to first inbox. Start the timer immediately before the provision call leaves the client. Stop it when the provisioned identity response returns. Typical live figure: ~0.15s.

Provision an identity — one call, no signup

The public one-call demo is POST /alias. No signup, no verification, no body required. Every field below is optional; the alias is auto-generated if you omit it.

curl -X POST https://getcourier.dev/alias \
  -H "content-type: application/json" \
  -d '{ "purpose": "agent-demo" }'

Response (HTTP 201)

{
  "success": true,
  "alias": {
    "alias": "generic-1a25fc7c",
    "inbox_id": "24936745",
    "read_token": "ck_read_...",
    "purpose": "agent-demo",
    "created_at": "2026-08-02T14:13:15.997Z"
  },
  "read_token": "ck_read_...",
  "identity": {
    "did": "did:courier:default:6818378494c9ef0f",
    "public_key": { "kty": "OKP", "crv": "Ed25519", "alg": "EdDSA", "value": "MCowBQYD..." },
    "fingerprint": "6818378494c9ef0f",
    "capabilities": [ { "type": "inbox", "id": "24936745" } ]
  }
}

Keep the read_token — it is inbox-scoped and shown once. It is how you read this inbox, and only this inbox.

Read messages — full codes for the token holder

Authenticate with the inbox-scoped read_token. The holder of an inbox's read token sees that inbox's extracted codes in full. Any other token gets 403 NOT_OWNER; no token gets 401.

curl https://getcourier.dev/inbox/<inbox_id>/messages \
  -H "authorization: Bearer $GETCOURIER_READ_TOKEN"

Message shape

{
  "messages": [{
    "id": 2923,
    "inbox_id": "24936745",
    "subject": "Your verification code",
    "from": "accounts@example.net",
    "classification": "verification_platform",
    "codes": [ { "type": "6-digit", "code": "884213" } ],
    "links": [ { "type": "verification", "domain": "example.net" } ],
    "received_at": "2026-08-02T14:14:30Z"
  }],
  "inbox_id": "24936745"
}

Rate limits

Provisioning (POST /alias) is rate-limited per client. On a burst you receive HTTP 429 with a JSON body and a Retry-After header:

{ "error": true, "code": "RATE_LIMITED",
  "message": "Too many requests. Slow down and retry.",
  "retryable": true, "retry_after_seconds": 10 }

Back off for retry_after_seconds and retry. Steady single-request pacing is not limited.

BYOD (bring your own domain)

Point a subdomain's MX at mail.getcourier.dev and mail to any local-part resolves to the matching alias. Production apex domains that already carry mail are never taken — use a dedicated subdomain (e.g. ai.yourdomain.com).

Machine files