API Reference

Complete endpoint reference for the inboxes backend API.

Authentication

All protected endpoints require a valid JWT in an httpOnly cookie named token. The cookie is set on login/signup/claim and cleared on logout.

Signing: HMAC-SHA256 (HS256)
Expiry: 7 days
Flags: HttpOnly, SameSite=Lax, Secure (HTTPS), Path=/

JWT claims: user_id, org_id, role (admin | member), jti, iat, exp

CSRF protection: All state-changing requests must include an X-Requested-With header (any non-empty value). Requests without it receive 403 Forbidden.

Error format

{ "error": "human-readable message" }

Common status codes: 400 (validation), 401 (unauthenticated), 403 (forbidden), 404 (not found), 409 (conflict), 422 (unprocessable), 429 (rate limited), 500 (server error).

Rate limits

Endpoint	Limit	Window
`POST /api/auth/signup`	5	1 hour
`POST /api/auth/login`	10/IP + 10/email	15 min
`POST /api/auth/forgot-password`	3/IP + 3/email	1 hour
`POST /api/emails/send`	20/IP + 30/user	60 sec
`POST /api/setup`	3	15 min
Admin cron/jobs	5	60 sec

Public endpoints

No authentication required.

Health

Method	Path	Description
`GET`	`/api/health`	Service health check
`GET`	`/api/config`	Public runtime configuration

Setup (self-hosted only)

Available only when STRIPE_KEY is unset.

Method	Path	Description
`GET`	`/api/setup/status`	Check if initial setup is needed
`POST`	`/api/setup`	Create first admin account and org
`POST`	`/api/setup/validate-key`	Validate a Resend API key

Auth

Method	Path	Description
`POST`	`/api/auth/signup`	Register a new account
`POST`	`/api/auth/login`	Log in, receive JWT cookie
`POST`	`/api/auth/forgot-password`	Send password reset email
`POST`	`/api/auth/reset-password`	Reset password with token
`POST`	`/api/auth/claim`	Claim an invited account
`POST`	`/api/auth/verify-email`	Verify email with 6-digit code

Webhooks

Method	Path	Description
`POST`	`/api/webhooks/resend/{orgId}`	Resend webhook receiver (Svix signature-verified)
`POST`	`/api/webhooks/stripe`	Stripe webhook receiver (commercial mode only)

WebSocket

Method	Path	Description
`GET`	`/api/ws`	WebSocket connection (authenticates via JWT cookie)

Protected endpoints

Require valid JWT cookie. All state-changing requests require X-Requested-With header.

Org settings

Method	Path	Auth	Description
`GET`	`/api/orgs/settings`	Any user	Get org settings
`PATCH`	`/api/orgs/settings`	Admin	Update org settings

User profile

Method	Path	Description
`GET`	`/api/users/me`	Get current user profile
`PATCH`	`/api/users/me`	Update profile (name)
`PATCH`	`/api/users/me/password`	Change password
`GET`	`/api/users/me/preferences`	Get user preferences
`PATCH`	`/api/users/me/preferences`	Update preferences (merge), including the undo-send delay
`PATCH`	`/api/users/me/signature`	Update the user's email signature
`GET`	`/api/users/me/sessions`	List active sessions
`DELETE`	`/api/users/me/sessions/{jti}`	Revoke a session

Threads

Method	Path	Description
`GET`	`/api/threads`	List threads
`PATCH`	`/api/threads/bulk`	Bulk action on multiple threads
`GET`	`/api/threads/{id}`	Get thread with all emails
`PATCH`	`/api/threads/{id}/read`	Mark thread as read
`PATCH`	`/api/threads/{id}/unread`	Mark thread as unread
`PATCH`	`/api/threads/{id}/star`	Toggle or set star
`PATCH`	`/api/threads/{id}/archive`	Move to archive
`PATCH`	`/api/threads/{id}/trash`	Move to trash (purged after 30 days when the trash collector is enabled)
`PATCH`	`/api/threads/{id}/spam`	Mark as spam or not-spam
`PATCH`	`/api/threads/{id}/snooze`	Snooze or unsnooze until a given time
`PATCH`	`/api/threads/{id}/mute`	Mute or unmute the thread
`PATCH`	`/api/threads/{id}/move`	Move to a label/folder
`DELETE`	`/api/threads/{id}`	Permanently delete (must be in trash)

Emails

Method	Path	Description
`POST`	`/api/emails/send`	Send an email (queued via job system). Accepts an optional `scheduled_at` time up to 30 days out
`POST`	`/api/emails/{id}/cancel-send`	Undo send - cancel an email inside its undo window
`GET`	`/api/emails/search`	Search emails. Supports `from:`, `to:`, `has:attachment`, `before:`, `after:`, plus `label` and `page` params
`POST`	`/api/emails/{id}/retry`	Re-queue a failed outbound email
`GET`	`/api/bounces`	List blocked (bounced) recipients; blocks expire after 30 days
`DELETE`	`/api/bounces/{id}`	Unblock a recipient (admin only)

Forwarding rules & auto-replies

Rules are per-alias. Members manage rules for their own aliases; admins manage all of them. Org policy toggles can disable forwarding, auto-replies, or external forwarding for the whole org.

Method	Path	Description
`GET`	`/api/forwarding-rules`	List forwarding rules
`POST`	`/api/forwarding-rules`	Create a forwarding rule
`PATCH`	`/api/forwarding-rules/{id}`	Update a forwarding rule
`DELETE`	`/api/forwarding-rules/{id}`	Delete a forwarding rule
`GET`	`/api/auto-replies`	List auto-replies
`POST`	`/api/auto-replies`	Create or update an auto-reply for an alias
`DELETE`	`/api/auto-replies/{id}`	Delete an auto-reply

Domains

Method	Path	Description
`GET`	`/api/domains`	List visible domains
`POST`	`/api/domains`	Add a new domain
`POST`	`/api/domains/{id}/verify`	Verify domain DNS records
`DELETE`	`/api/domains/{id}`	Soft-delete a domain (admin only)
`PATCH`	`/api/domains/reorder`	Reorder sidebar domains
`POST`	`/api/domains/sync`	Sync domain list from Resend

Users (admin)

Method	Path	Description
`GET`	`/api/users`	List org users
`POST`	`/api/users/invite`	Invite a new user
`PATCH`	`/api/users/{id}/disable`	Disable user
`PATCH`	`/api/users/{id}/role`	Change user role

Aliases

Method	Path	Description
`GET`	`/api/aliases`	List all aliases
`POST`	`/api/aliases`	Create alias (admin only)
`PATCH`	`/api/aliases/{id}`	Update alias name (admin only)
`DELETE`	`/api/aliases/{id}`	Delete alias (admin only)
`PATCH`	`/api/aliases/{id}/default`	Set as default send-from alias

Drafts

Method	Path	Description
`GET`	`/api/drafts`	List drafts
`POST`	`/api/drafts`	Create draft
`PATCH`	`/api/drafts/{id}`	Update draft
`DELETE`	`/api/drafts/{id}`	Delete draft
`POST`	`/api/drafts/{id}/send`	Send a draft, now or at an optional `scheduled_at` time (up to 30 days out)
`POST`	`/api/drafts/{id}/cancel-schedule`	Cancel a scheduled send and keep the draft

Labels

Method	Path	Description
`GET`	`/api/labels`	List custom labels
`POST`	`/api/labels`	Create label
`PATCH`	`/api/labels/reorder`	Reorder labels in the sidebar
`PATCH`	`/api/labels/{id}`	Rename label
`DELETE`	`/api/labels/{id}`	Delete label

Attachments

Method	Path	Description
`POST`	`/api/attachments/upload`	Upload attachment (max 10MB, multipart/form-data)
`GET`	`/api/attachments/{id}/meta`	Get attachment metadata
`GET`	`/api/attachments/{id}`	Download attachment

Sync

Method	Path	Description
`POST`	`/api/sync`	Start an email sync job (admin only)
`GET`	`/api/sync/{id}`	Get sync job status

Billing

Method	Path	Auth	Description
`GET`	`/api/billing`	Any user	Get billing status and plan info. Includes `read_only` for lapsed plans; a lapsed org keeps read access, writes return `402`
`POST`	`/api/billing/checkout`	Admin	Create Stripe checkout session
`POST`	`/api/billing/portal`	Admin	Create Stripe billing portal URL

Agent credentials (MCP)

These endpoints manage the API keys and OAuth connections that MCP clients use. See MCP for the full agent integration guide, including the /mcp endpoint and the OAuth discovery routes.

Method	Path	Description
`GET`	`/api/agent-keys`	List your API keys and OAuth connections
`POST`	`/api/agent-keys`	Create an API key. The raw key is returned once and stored only as a SHA-256 hash
`DELETE`	`/api/agent-keys/{id}`	Revoke a key or OAuth connection

Admin-only endpoints

Require role = admin. Protected by JWT auth.

Method	Path	Description
`POST`	`/api/cron/purge-trash`	Manually trigger trash purge
`POST`	`/api/cron/cleanup-webhooks`	Clean up stale Resend webhooks
`GET`	`/api/admin/jobs`	List email job queue status

System settings (self-hosted, owner only)

Method	Path	Description
`GET`	`/api/system/email`	Get system email configuration
`PATCH`	`/api/system/email`	Update system from-address

Org deletion (owner only)

Method	Path	Description
`DELETE`	`/api/orgs`	Soft-delete organization
`DELETE`	`/api/orgs/hard`	Permanently delete organization