Sending

Send email

A single channel-tagged endpoint sends your transactional and marketing email.

Send an email

Send an email with a single call to POST /v1/send. The SDKs expose an ergonomic emails.send helper; the raw API takes a channel-tagged body.

The request body

The raw API accepts the following fields.

channelstringRequired
email — the only generally-available send channel.
idempotency_keystringOptional
Unique key per logical send. Optional — auto-generated if omitted. Retries with the same key return the original result.
destinationobjectRequired
Channel-specific recipient. For email: { email }.
payloadobjectRequired
Channel-specific content. For email: { subject, body_html, body_text }.
message_typestringOptional
transactional (default) or marketing.
metadataobjectOptional
Per-send options. For email, { from_email } sets the sender (must be a verified domain). from_email accepts a bare address ([email protected]) or a name-addr with a display name ("Acme" <[email protected]>).
template_idstringOptional
Render a stored template instead of an inline payload.
template_varsobjectOptional
Variables interpolated into the template.

Sender name

By default inboxes show the bare address you send from. To show a friendly name instead, set metadata.from_email to a name-addr — a display name followed by the address in angle brackets:

"metadata": { "from_email": "\"Acme Receipts\" <[email protected]>" }

The address must still belong to a verified sending domain. You can also set a default sender name per domain in the dashboard (Domains → your domain → Default sender name) — every send from that domain then shows the name automatically, and a per-send from_email name overrides it.

Idempotency

The idempotency_key is optional. If you omit it, the server auto-generates one (the SDKs generate a key for you before the request leaves your process). When you do pass one, retrying with the same key returns the original result instead of sending again, so network retries never double-send.

Reusing a key with a different payload returns 409 idempotency_key_reused — keys are bound to the request they first succeeded with.

Batch sending

Send many messages in one request with POST /v1/send/batch. Each item is processed independently; the response preserves request order with per-item success or error, so partial success is normal.

curl https://api.sendara.dev/v1/send/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '[
    { "channel": "email", "idempotency_key": "b1",
      "destination": { "email": "[email protected]" },
      "payload": { "subject": "Hi", "body_html": "<p>Hi</p>" } },
    { "channel": "email", "idempotency_key": "b2",
      "destination": { "email": "[email protected]" },
      "payload": { "subject": "Hi", "body_html": "<p>Hi</p>" } }
  ]'

Templates

Pass a template_id with template_vars instead of an inline payload to render a stored template — useful for keeping copy out of your codebase.

Message types

Set message_type to transactional (the default) for receipts, OTPs, and alerts, or marketing for campaigns. Marketing mail is subject to unsubscribe handling and suppression rules.

Other channels

Email is the only generally-available send channel today. The send endpoint is channel-tagged so the platform can grow into more channels, but the others are not available for production sends:

  • sms and voice OTP are gated and not enabled — sending with channel: "sms" or channel: "voice" returns 422 channel_not_enabled.
  • push and webhook are not production send channels.
PreviousAI agentsNextScheduled sends