First send via API
You need
Section titled “You need”- A project with a connected domain and sending permission for your sender address.
- An API key for that sender. It is shown once when you create it; store it in your secret manager right away. Creating a key asks for your second factor.
- The stream ID, shown with the credential. View API examples on the credential fills in the request below for you.
Quickest route
Section titled “Quickest route”- Open your project in Control, then API keys & SMTP.
- Choose View API examples on your key. Enter your recipient; a subject and message are already filled in.
- Set your saved key as
WENEED_API_KEYin your terminal and paste the generated cURL command. Sender, stream and message ID are filled in; the response and HTTP status are printed automatically. - Open Messages to follow delivery.
Keep the same command for a retry. Generating another example creates a new message identity. A Node.js alternative is available on the same page.
API request reference
Section titled “API request reference”curl -sS "https://api.weneed.email/v1/emails" \ -H "Authorization: Bearer $WENEED_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: signup-7f3c2a91-welcome" \ -d '{ "stream_id": "YOUR-STREAM-ID", "from": { "email": "hello@yourdomain.com", "name": "Your App" }, "to": [ { "email": "person@example.com" } ], "subject": "Welcome", "text": "Thanks for signing up." }'The response is 202 with a message ID. That means the message is stored and queued. Open the
message in the message timeline to follow delivery.
The idempotency key matters
Section titled “The idempotency key matters”Idempotency-Key is required: 16 to 128 printable characters that name this one intent, for
example the sign-up event’s ID. If the request times out, send it again with the same key and
the same body. You get the original message back instead of a duplicate.
Never generate a new key for a retry. Read Retries and duplicates.
Optional fields
Section titled “Optional fields”| Field | Use |
|---|---|
html |
HTML body. Send text, html or both. |
reply_to |
One reply address. Verifying a domain doesn’t create a mailbox, so use an inbox that exists. |
expires_at |
Don’t send after this time. Useful for one-time codes. |
tags |
Up to 10 key–value pairs for your own filtering. |
See the API reference for every endpoint and response code.