DEVELOPERS / REST

API overview

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

Base URL

All public REST routes use HTTPS beneath:

EXAMPLE

https://startupmail.dev/v1

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

OpenAPI specification

Agents and API tooling can discover the public REST API automatically from:

EXAMPLE

https://startupmail.dev/openapi.json

The specification covers the API-key-authenticated /v1 routes. The Streamable HTTP MCP endpoint uses protocol-level tool discovery instead; see MCP for agents.

Create an API key

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

Capability	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
`mailboxes:write`	Provision mailboxes through the API
`domains:write`	Start domain verification
`tenants:read`, `tenants:write`	Manage isolated agent/customer tenants
`drafts:read`, `drafts:write`	Review, create, and schedule drafts
`drafts:send`	Approve or schedule a stored draft
`policies:write`	Configure mailbox communication allow/block lists

Authenticate

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

EXAMPLE

curl https://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_capability",
    "message": "This API key requires the mail:read capability."
  }
}

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.

See Agent inboxes for provisioning, resource-scoped keys, drafts, and policies.

Loading documentation…

Create an API key

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

Capability

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

mailboxes:write

Provision mailboxes through the API

domains:write

Start domain verification

tenants:read, tenants:write

Manage isolated agent/customer tenants

drafts:read, drafts:write

Review, create, and schedule drafts

drafts:send

Approve or schedule a stored draft

policies:write

Configure mailbox communication allow/block lists

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_capability",
    "message": "This API key requires the mail:read capability."
  }
}

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.

See Agent inboxes for provisioning, resource-scoped keys, drafts, and policies.