API reference

Base URL — https://agent.waterr.ai Auth — Authorization: Bearer <key> on every request. See Authentication.

Inboxes

Method	Path	Purpose
`POST`	`/v0/inboxes`	Create an inbox
`GET`	`/v0/inboxes`	List inboxes in scope
`GET`	`/v0/inboxes/{inbox_id}`	Read one
`PATCH`	`/v0/inboxes/{inbox_id}`	Update `display_name`
`DELETE`	`/v0/inboxes/{inbox_id}`	Delete, with its whole database

Messages

Method	Path	Purpose
`POST`	`/v0/inboxes/{inbox_id}/messages/send`	Send a message
`POST`	`/v0/inboxes/{inbox_id}/messages/{message_id}/reply`	Reply on the thread
`POST`	`/v0/inboxes/{inbox_id}/messages/{message_id}/forward`	Forward
`GET`	`/v0/inboxes/{inbox_id}/messages`	List messages
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}`	Read one
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}/raw`	Original MIME source
`PATCH`	`/v0/inboxes/{inbox_id}/messages/{message_id}`	Update labels
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`	Fetch an attachment

Threads

Method	Path	Purpose
`GET`	`/v0/inboxes/{inbox_id}/threads`	List threads in one inbox
`GET`	`/v0/inboxes/{inbox_id}/threads/{thread_id}`	Read a thread with its messages
`GET`	`/v0/threads`	List across every inbox in scope
`DELETE`	`/v0/inboxes/{inbox_id}/threads/{thread_id}`	Delete a thread

Drafts

Method	Path	Purpose
`POST`	`/v0/inboxes/{inbox_id}/drafts`	Create a draft
`GET`	`/v0/inboxes/{inbox_id}/drafts`	List drafts
`GET`	`/v0/inboxes/{inbox_id}/drafts/{draft_id}`	Read one
`PATCH`	`/v0/inboxes/{inbox_id}/drafts/{draft_id}`	Edit, including `send_at`
`POST`	`/v0/inboxes/{inbox_id}/drafts/{draft_id}/send`	Send it
`DELETE`	`/v0/inboxes/{inbox_id}/drafts/{draft_id}`	Discard

Search and events

Method	Path	Purpose
`GET`	`/v0/inboxes/{inbox_id}/search?q=`	Full-text search in one inbox
`GET`	`/v0/inboxes/{inbox_id}/events`	Recent events for an inbox
`GET`	`/v0/metrics`	Service metrics
`GET`	`/health`	Health check — the only unauthenticated route

Lists

Method	Path	Purpose
`GET`	`/v0/inboxes/{inbox_id}/lists/{direction}/{type}`	List entries
`POST`	`/v0/inboxes/{inbox_id}/lists/{direction}/{type}`	Add an entry
`GET`	`/v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}`	Read one
`DELETE`	`/v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}`	Remove

direction is send, receive or reply. type is allow or block.

Webhooks

Method	Path	Purpose
`POST`	`/v0/webhooks`	Create — returns the signing `secret` once
`GET`	`/v0/webhooks`	List
`GET`	`/v0/webhooks/{webhook_id}`	Read one
`PATCH`	`/v0/webhooks/{webhook_id}`	Update url, events, or `enabled`
`DELETE`	`/v0/webhooks/{webhook_id}`	Delete
`GET`	`/v0/webhooks/{webhook_id}/deliveries`	Delivery history
`POST`	`/v0/webhooks/deliveries/{delivery_id}/retry`	Force a retry

Pods

Method	Path	Purpose
`POST`	`/v0/pods`	Create a pod
`GET`	`/v0/pods`	List pods
`GET`	`/v0/pods/{pod_id}`	Read one
`DELETE`	`/v0/pods/{pod_id}`	Delete — refused while it holds inboxes
`POST`	`/v0/pods/{pod_id}/inboxes`	Create an inbox in the pod
`GET`	`/v0/pods/{pod_id}/inboxes`	List its inboxes
`GET`	`/v0/pods/{pod_id}/threads`	List threads across the pod

Domains

Method	Path	Purpose
`POST`	`/v0/domains`	Register a domain, get its DNS records
`GET`	`/v0/domains`	List
`GET`	`/v0/domains/{domain_id}`	Read one, with verification state
`POST`	`/v0/domains/{domain_id}/verify`	Re-check DNS
`DELETE`	`/v0/domains/{domain_id}`	Remove

API keys

Admin key only.

Method	Path	Purpose
`POST`	`/v0/api-keys`	Mint a scoped key — returns `api_key` once
`GET`	`/v0/api-keys`	List metadata
`DELETE`	`/v0/api-keys/{key_id}`	Revoke

WebSocket

Path	Purpose
`/v0/ws`	Hub socket with subscribe filters
`/v0/inboxes/{inbox_id}/ws`	One socket for one inbox

Both accept ?api_key= since browsers cannot set headers on a WebSocket.

Conventions

Pagination

List endpoints take limit and a cursor. Responses are wrapped:

{
  "data": [ "..." ],
  "count": 50,
  "next_cursor": "eyJrIjoi...",
  "next_page_token": "eyJrIjoi..."
}

next_cursor and next_page_token are the same value under two names. Pass either back as ?cursor= or ?page_token=. Both aliases exist so client libraries written against other mailbox APIs work unchanged. When the pagination fields are absent, you have reached the end.

Identifiers

Prefix	Resource
`msg_`	Message
`thd_`	Thread
`dft_`	Draft
`att_`	Attachment
`whk_`	Webhook
`dlv_`	Webhook delivery
`evt_`	Event
`pod_`	Pod
`dom_`	Domain
`key_`	API key

Inboxes are the exception: an inbox’s identifier is its email address.

Errors

Failures return a consistent body, and the code is stable — match on it rather than on the message text.

{
  "error": {
    "code": "validation_error",
    "message": "username may not contain '+', which is reserved for thread tokens"
  }
}

Code	Status	Meaning
`unauthorized`	401	Missing or invalid key
`forbidden`	403	Valid key, out of scope — or a list refused the send
`not_found`	404	No such resource
`conflict`	409	State prevents it, e.g. deleting a non-empty pod
`payload_too_large`	413	Over the size limit
`validation_error`	422	Malformed or invalid input
`rate_limited`	429	Over 300 requests / 60s for this key
`internal_error`	500	Unexpected failure
`not_implemented`	501	Not available on this deployment
`provider_error`	502	The mail transport failed

Some errors carry a details object with structured context — a list refusal names the direction and recipient.

Getting Started

Building

Reference

Inboxes

Messages

Threads

Drafts

Search and events

Lists

Webhooks

Pods

Domains

API keys

WebSocket

Conventions

Identifiers

Errors

​Inboxes

​Messages

​Threads

​Drafts

​Search and events

​Lists

​Webhooks

​Pods

​Domains

​API keys

​WebSocket

​Conventions

​Pagination

​Identifiers

​Errors

Inboxes

Messages

Threads

Drafts

Search and events

Lists

Webhooks

Pods

Domains

API keys

WebSocket

Conventions

Pagination

Identifiers

Errors