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

First send via API

  • 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.
  1. Open your project in Control, then API keys & SMTP.
  2. Choose View API examples on your key. Enter your recipient; a subject and message are already filled in.
  3. Set your saved key as WENEED_API_KEY in your terminal and paste the generated cURL command. Sender, stream and message ID are filled in; the response and HTTP status are printed automatically.
  4. 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.

Terminal window
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.

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.

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.