DEVELOPERS / REST

API overview

Authenticate to the v1 REST API, choose scopes, and handle responses and errors.

Base URL

All public REST routes use HTTPS beneath:

EXAMPLE

https://api.startupmail.dev/v1

The SDK uses this base by default. During local development, pass your local origin as baseUrl.

Create an API key

Open Settings → Developers → API keys. Give the key a workload-specific name, optional description and expiry, and only the scopes it needs. The full secret is shown once.

Scope	Allows
`mailboxes:read`	List accessible mailbox metadata
`mail:read`	List threads, read threads, and download attachments
`mail:send`	Upload attachments, send, and reply
`webhooks:write`	List, create, and delete webhook endpoints

Authenticate

Send the key as a Bearer token. Never expose it in browser code or commit it to source control.

EXAMPLE

curl https://api.startupmail.dev/v1/mailboxes \
  -H "Authorization: Bearer $STARTUPMAIL_API_KEY" \
  -H "Accept: application/json"

Response shape

Successful JSON resources are wrapped in data. Sending returns 202; creation commonly returns 201; a successful delete returns 204 with no body.

Errors use a stable code and a readable message:

EXAMPLE

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key requires the mail:read scope."
  }
}

The response x-request-id is useful when contacting support. Clients should handle 401, 403, 404, 413, and 429 explicitly and retry only when the operation is safe to repeat.