api reference

Domains API

Discover the configured inbound domains available for address creation.

Use this endpoint before address creation when the client needs to present a valid domain selector, confirm the default inbound domain, or reflect an enforced inbox prefix in the UI.

List configured domains

GET/api/domains

Return the inbound domains and current inbox-retention defaults currently configured for the Worker.

Auth: Authenticated endpoint. Organization scope is not required for this route.
Success: 200

Request headers

Request headers
Header	Example	Requirement	Details
`Cookie session or X-API-Key`	`Cookie: <better-auth session> or X-API-Key: spin_...`	Required	All documented product endpoints require an authenticated user session or a valid Better Auth API key.

Success response

Success response
Field	Type	Details
`items`	`string[]`	List of configured inbound domains.
`default`	`string \| null`	Default domain suggested to clients. It is the first configured domain when available.
`forcedLocalPartPrefix`	`string \| null`	Forced inbox local-part prefix configured on the Worker. When non-null, clients should treat <prefix>- as always applied by the backend.
`maxReceivedEmailsPerOrganization`	`number`	Current organization-wide ceiling for stored emails across all inboxes in the active deployment.
`maxReceivedEmailsPerAddress`	`number`	Current default and hard cap for stored emails per inbox in the active deployment.

Common error responses

Common error responses
Status	Error	When it happens
`401`	`unauthorized`	The request does not include a valid session or API key.
`403`	`email verification required`	The authenticated user has not verified their email address.
`500`	`No email domains configured`	The Worker has no EMAIL_DOMAINS value configured.

Example request

curl "https://api.spinupmail.com/api/domains" \
  -H "X-API-Key: spin_..."

Example response

{
  "items": ["spinupmail.dev", "qa.spinupmail.dev"],
  "default": "spinupmail.dev",
  "forcedLocalPartPrefix": "temp",
  "maxReceivedEmailsPerOrganization": 1000,
  "maxReceivedEmailsPerAddress": 100
}