Skip to content
Invitation-only alpha. Features and limits may change as we learn from testing.

API reference

Base URL: https://api.weneed.email. Authenticate every request with Authorization: Bearer <API key>.

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.

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

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.

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.

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.

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.

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.