API Introduction

All gork.email endpoints live under a single versioned base URL:

cURL

https://api.gork.email

Every public endpoint is namespaced under /v1 (e.g. POST /v1/messages/send). The /v1 prefix is immutable — backwards-compatible changes never break existing integrations.

Authentication

Authenticate with a bearer API key on every request:

cURL

curl https://api.gork.email/v1/inboxes \
  -H "Authorization: Bearer gork_live_YOUR_API_KEY"

Keys are formatted as gork_live_... (production) or gork_test_... (test). Only the SHA-256 hash is stored server-side — the raw key is shown exactly once at creation and can never be retrieved again.

A missing or malformed Authorization header returns 401 unauthorized. A revoked or unknown key returns 401 invalid_api_key. A key whose format does not start with gork_ returns 401 invalid_api_key_format.

Scopes

Every key carries a set of scopes. Endpoints declare the scope they require, and a key without it receives 403 insufficient_scope. A key with the * wildcard scope (the default for unbound keys) may call everything.

Scope	Grants access to
`inboxes:read`	List and fetch inboxes
`inboxes:write`	Provision and deactivate inboxes
`messages:read`	List, search, and fetch messages; read attachments
`messages:send`	Send, schedule, delete, and cancel messages; manage drafts
`threads:read`	List and fetch conversation threads
`webhooks:read`	List webhooks and delivery logs
`webhooks:write`	Register, rotate, and delete webhooks
`keys:read`	List API keys (prefixes only, never hashes)
`keys:write`	Create and revoke API keys
`domains:read`	List custom domains
`domains:write`	Register, verify, and delete custom domains
`organization:read`	Read organization profile and member list
`suppressions:read`	List suppressed recipients
`suppressions:write`	Add and remove suppressions

Resource wildcards are also honored: messages:* covers both messages:read and messages:send.

Inbox-bound agent keys (created with an inboxId) may only hold mail scopes — inboxes:read, messages:read, messages:send, threads:read — and every call is confined to their own inbox. See API Keys.

Success envelope

Every successful response wraps its payload in a data envelope:

200 OK

{
  "data": {
    "id": "inb_728af980b4e",
    "address": "support@try.gork.email"
  }
}

List endpoints return an array under data:

200 OK

{
  "data": []
}

Error envelope

Errors always use the same shape:

422 Unprocessable Entity

{
  "error": {
    "code": "recipient_suppressed",
    "message": "Cannot send email. Recipient ... is suppressed (bounce).",
    "details": {}
  }
}

Field	Always present?	Meaning
`error.code`	Yes	Stable machine-readable code (e.g. `inbox_not_found`, `validation_failed`). Branch on this, not on the message.
`error.message`	Yes	Human-readable explanation.
`error.details`	No	Extra context (validation breakdowns, suppression reason, quota diagnostics).

Idempotency

POST /v1/messages/send accepts an Idempotency-Key header. Replaying a request with the same key returns the original result instead of sending twice:

cURL

curl -X POST https://api.gork.email/v1/messages/send \
  -H "Authorization: Bearer gork_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "inboxId": "inb_728af980b4e", "to": ["prospect@acmecorp.com"], "subject": "Hi" }'

Keys are capped at 255 characters — longer values are rejected with 400 validation_failed.
A replayed delivery returns HTTP 200 (not 201) with an Idempotent-Replayed: true response header.
Always generate a fresh UUID per logical send, and reuse it only when retrying that same send after a network failure.

Rate limits

Requests are limited to 240 requests per minute per organization. Every authenticated response carries the current budget:

Header	Meaning
`X-RateLimit-Limit`	The window allowance (`240`).
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.

Exceeding the budget returns 429 rate_limit_exceeded. Back off and retry after the reset time.

Health and machine-readable spec

GET https://api.gork.email/health returns { "status": "healthy", "service": "gork.email", ... } with no authentication. Use it for uptime checks.
GET https://api.gork.email/openapi.json serves the full OpenAPI specification — the same source SDKs and agent tool definitions are generated from.

​Authentication

​Scopes

​Success envelope

​Error envelope

​Idempotency

​Rate limits

​Health and machine-readable spec

Authentication

Scopes

Success envelope

Error envelope

Idempotency

Rate limits

Health and machine-readable spec