API reference
Base URL: https://api.weneed.email. Authenticate every request with
Authorization: Bearer <API key>.
Endpoints
Section titled “Endpoints”| Method | Path | Purpose |
|---|---|---|
POST |
/v1/emails |
Submit a message. Requires Idempotency-Key. |
GET |
/v1/emails |
List messages from the last 30 days, newest first. Needs read scope. |
GET |
/v1/emails/{id} |
Read a message’s status, reason and history. Needs read scope. |
POST |
/v1/emails/{id}/cancel |
Cancel a message that hasn’t been sent yet. |
GET |
/v1/usage |
Read your usage and remaining allowance. |
GET |
/v1/suppressions?address= |
Check whether one address is blocked. Needs suppressions:read. |
Keys are either send-only or send, read email metadata and read usage. Read keys issued
from now on can also look up blocked recipients (suppressions:read); existing keys keep the
permissions they were issued with. A send-only key can’t look up status; use the dashboard instead. Keys have no expiry by default. You can choose an optional expiry for temporary access, and rotate or revoke keys in Control at any time. See API keys and SMTP credentials.
Request body for POST /v1/emails
Section titled “Request body for POST /v1/emails”| Field | Required | Notes |
|---|---|---|
stream_id |
yes | UUID shown with your credential |
from |
yes | { email, name? }; must match your approved sender |
to |
yes | Exactly one { email, name? } |
subject |
yes | Up to 998 characters |
text / html |
at least one | Body |
reply_to |
no | Exactly one { email, name? } |
expires_at |
no | ISO 8601 time; not sent afterwards |
tags |
no | Up to 10 keys (1–64 characters), values up to 256 characters |
Listing messages: GET /v1/emails
Section titled “Listing messages: GET /v1/emails”Query parameters, all optional:
| Parameter | Notes |
|---|---|
state |
One submission state. |
outcome |
One recipient outcome. |
transport |
api, smtp or unknown. |
from, to |
UTC times such as 2026-10-01T00:00:00Z; from inclusive, to exclusive. |
id |
One message ID. |
tag |
Exact key:value, for example order:1234. The key ends at the first colon. |
cause |
The reason code of the current state. |
limit |
1–100, default 25. |
cursor |
The next_cursor from the previous page. |
Each item has id, accepted_at, submission_state, recipient_outcome, transport,
simulated and tags (null when historical tags were not retained). The list never returns the subject, body or recipient, and there is no
search by recipient. next_cursor is null on the last page. A cursor only works with the same
key and the same filters; anything else returns 400.
Reading one message: GET /v1/emails/{id}
Section titled “Reading one message: GET /v1/emails/{id}”The fields you already use are unchanged. After them come:
| Field | Meaning |
|---|---|
tags |
The tags you sent, or null when historical tags were not retained. |
reason |
Why the message is in its current state: code, category, retry, or null. |
attempts |
The newest 25 sending attempts: number, created_at, kind, code, route and route_label (nullable when not recorded). |
attempt_total |
How many attempts exist in total. |
feedback |
Delivery reports received: action, enhanced status, occurred_at. |
current_blockers |
While the message can still be sent: what currently stops it, as codes. |
trace |
Observed route steps. Missing observations do not prove a step failed or never happened. |
trace_limits |
Gaps in retained evidence; an absent event is not a delivery result. |
The timeline is complete by default. To page it, pass timeline_limit (1–100) and then the
timeline_cursor from timeline_next_cursor.
Checking an address: GET /v1/suppressions
Section titled “Checking an address: GET /v1/suppressions”Pass one exact address. The answer has address, suppressed, reason (hard_bounce,
complaint or platform), since (null when not recorded) and source_email_id (only when the
message belongs to this project). There is no list or export. See
Bounces and suppressed addresses.
Response codes
Section titled “Response codes”| Code | Meaning |
|---|---|
202 |
Stored and queued (or recorded as suppressed). Not yet delivered. |
400 |
Malformed request. |
401 |
Missing, wrong or expired key. |
403 |
The key isn’t allowed to do this, for example the wrong sender or scope. |
404 |
Message or stream not found for this key. |
409 |
Conflict, for example an idempotency key reused with different content. |
413 |
Message too large. |
422 |
Valid JSON that can’t be accepted, for example an unapproved sender. |
429 |
Rate limit or allowance reached. error.reason names the limit; see below. |
503 |
Temporarily unavailable or result uncertain. Retry with the same key and body. |
Every error body has error.code and error.message. The API errors
page lists every code with what it means and whether repeating the request can succeed.
Limits and Retry-After
Section titled “Limits and Retry-After”A 429 for a sending limit carries error.reason and, when waiting helps, a Retry-After header
in seconds:
error.reason |
Retry-After |
|---|---|
daily_limit_reached |
Until the next midnight UTC. |
monthly_limit_reached |
Until the first day of the next month, UTC. |
rate_limited |
The length of the rate window. |
pending_limit_reached |
60 seconds. |
lifetime_limit_reached |
None: waiting does not help. Contact support. |
service_capacity |
Until the next window when it resets, or none. |
Repeat with the same Idempotency-Key after the wait. Other 429 responses keep
Retry-After: 60.