Send an email

POST /emails accepts one email, validates it, and queues it for delivery. The response contains the email ID. Delivery happens afterward, and you follow it in the dashboard, with GET /emails/{id}, or through webhooks.

This endpoint works with a sending_access key. See Authentication.

Request

curl -X POST https://api.sooner.dev/emails \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "from": "Acme <orders@mail.yourcompany.com>",
    "to": ["ada@example.com"],
    "cc": ["accounts@example.com"],
    "reply_to": "support@yourcompany.com",
    "subject": "Your order is confirmed",
    "html": "<p>Thanks for your order.</p>",
    "text": "Thanks for your order.",
    "headers": { "X-Entity-Ref-ID": "order-1042" },
    "tags": [{ "name": "category", "value": "order_confirmation" }]
  }'

{ "id": "01jcz8w3f2x9k4m7n6p5q2r1s0" }

With the Node SDK:

import { Resend } from "resend";

const resend = new Resend(process.env.SOONER_API_KEY, { baseUrl: "https://api.sooner.dev" });

const { data, error } = await resend.emails.send(
  {
    from: "Acme <orders@mail.yourcompany.com>",
    to: ["ada@example.com"],
    subject: "Your order is confirmed",
    html: "<p>Thanks for your order.</p>",
  },
  { idempotencyKey: "order-1042-confirmation" },
);

Parameters

The Idempotency-Key request header is also supported. See Idempotency.

Limits and rules

• At most 50 recipients in total across to, cc and bcc.
• Each address list is limited to 50 entries, and every address must be valid. Names are allowed, as in Ada Lovelace <ada@example.com>.
• You must provide at least one of html, text or template.
• The from domain must be verified in the project that owns the API key. If the key is locked to a domain, the from address must be on that domain.
• Every recipient in to, cc and bcc receives the same message. To send different content to different people in one request, use batch sending.

What happens after you send

The API validates the request, records it, and returns the ID with status 200. At that point the email has status queued, or scheduled if you set scheduled_at.

Sooner then sends the message and records events as they happen. The email status only moves forward through this order:

A late delivery_delayed event can never move an email back from delivered. failed and canceled are final. Opens and clicks are recorded as events but do not change the status. The last_event field on the email shows the most recent event, for example opened.

Suppressed and opted-out recipients

If every recipient is on your team's suppression list, or the recipient has opted out of the topic_id you set, the request still succeeds and returns an ID. The email is recorded as failed with last_event set to suppressed, and it is not sent. It still counts toward your quota.

If only some recipients are suppressed, the others receive the email, and the suppressed addresses are dropped at send time.

Errors

See Errors for the response format, and the emails API reference to retrieve, list, reschedule and cancel emails.