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)
`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}/star`	Toggle or set star
`PATCH`	`/api/threads/{id}/archive`	Move to archive
`PATCH`	`/api/threads/{id}/trash`	Move to trash (30-day auto-purge)
`PATCH`	`/api/threads/{id}/spam`	Mark as spam or not-spam
`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)
`GET`	`/api/emails/search`	Search emails

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

Labels

Method	Path	Description
`GET`	`/api/labels`	List custom labels
`POST`	`/api/labels`	Create label
`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
`POST`	`/api/billing/checkout`	Admin	Create Stripe checkout session
`POST`	`/api/billing/portal`	Admin	Create Stripe billing portal URL

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