HTTP API overview
The Werkmail API is the same origin as the product. There is no separate “v1” host.
Base URL: https://werkmail.eu
https://werkmail.eu/api/practices/{id}/send
OpenAPI (YAML): https://werkmail.eu/openapi.yaml
GET /openapi.json returns JSON. GET /openapi.yaml returns YAML.
Health: https://werkmail.eu/healthz
The endpoint reference lists every shipped route and method. It matches the OpenAPI document and the live router.
Authentication
Send Authorization: Bearer <token> on /api/* except public routes (/api/reference, /api/reference.md) and the auth routes below.
| Token | Prefix / source | Scope |
|---|---|---|
| Session | OTP or password login | The signed-in member |
| Team API token | wm_team_… |
Manage the workspace |
| Project API token | wm_proj_… |
Send and read for one project |
| Operator admin | ADMIN_API_TOKEN or X-Admin-Token |
Platform admin |
Details: Authentication.
Public routes (no bearer)
| Method | Path | Purpose |
|---|---|---|
POST |
/api/auth/request-otp |
Email a sign-in code |
POST |
/api/auth/verify-otp |
Exchange code for a session bearer |
POST |
/api/auth/login-password |
Password login when enabled |
GET|POST |
/api/public/unsub |
Signed one-click unsubscribe |
GET |
/api/public/confirm |
DOI confirm |
POST |
/api/public/abuse |
Abuse report |
POST |
/api/public/hooks/{id}/send |
Inbound send hook (X-Werkmail-Hook-Secret) |
GET |
/openapi.yaml |
OpenAPI document (YAML) |
GET |
/openapi.json |
OpenAPI document as JSON |
GET |
/api/public/preferences |
Signed preference center |
GET|POST |
/api/public/portal |
Contact portal |
POST |
/api/public/subscribe |
Public double opt-in |
POST |
/api/public/waitlist |
Product waitlist |
Practice-scoped routes
Most product APIs live under /api/practices/{id}/…. {id} is the workspace UUID. Flat aliases (POST /api/emails, GET /api/emails, GET /api/emails/{id}, GET /api/emails/stats, POST /api/emails/send-bulk, /api/suppressions, POST /api/projects) use the token's workspace. Pass project_id when the token is not already scoped to one workspace.
Topic guides
- Send — single, batch, bulk, score, test
- Drop-in send APIs — Resend, Postmark, and Lettermint
- Messages — list, get, search, timeline
- Webhooks — subscribe and verify signatures
- Suppressions — team / project / route blocks
- Inbound — receive + send hook
- Lists and campaigns
- Errors
- Endpoint reference
Idempotency and errors
Retry-safe writes accept Idempotency-Key. Errors are JSON { "code", "error", "hint" } — see Errors.