Send one message

POST/v1/email

TypeScript sendora.email.send(message)

Python sendora.email.send(**message)

Key sk_… a server key

Accepts one message for delivery and answers at once with its id. Delivery, deferral, bounce and complaint arrive later as events on the message and as webhooks. With an Idempotency-Key, a retry within 24 hours gets the first answer again, marked by the Idempotent-Replayed header, and sends nothing twice.

Parameters

• idempotency-keyin headerstring

  Any text of 1 to 255 printable characters that identifies this request; the same key with a different body is refused.

Request body

• fromone of 2required

  The sender. Its domain must be a verified sending domain of the server.

  1. string (email)
  2. • emailstring (email)required
     • namestring (at least 1, at most 200 characters) or null

       A display name of up to 200 characters.

• streamIdstring (uuid)

  The stream of this server the message goes on; the default transactional stream when absent.

• toarray of one of 2, at least 1required

  Recipients; at most 50 across to, cc and bcc.

  1. string (email)
  2. • emailstring (email)required
     • namestring (at least 1, at most 200 characters) or null

       A display name of up to 200 characters.

• ccarray of one of 2

  Copied recipients, shown in the message.

  1. string (email)
  2. • emailstring (email)required
     • namestring (at least 1, at most 200 characters) or null

       A display name of up to 200 characters.

• bccarray of one of 2

  Blind-copied recipients.

  1. string (email)
  2. • emailstring (email)required
     • namestring (at least 1, at most 200 characters) or null

       A display name of up to 200 characters.

• subjectstring (at least 1, at most 998 characters)required

  The subject line.

• textstring (at least 1 character)

  The plain-text part. At least one of text and html is required.

• htmlstring (at least 1 character)

  The HTML part.

• headersmap of string to stringdefault {}

  Custom headers by name, at most 20. Sendora writes these itself, so a message may not set them: From, Sender, To, Cc, Bcc, Subject, Date, Message-ID, MIME-Version, Return-Path, Received, Delivered-To, DKIM-Signature, DomainKey-Signature, Authentication-Results, Received-SPF, and any name that starts with Content-, Resent-, ARC- or X-Kumo.

• attachmentsarray of object, at most 20

  At most 20. A message with its attachments encoded may be at most 10 MB.

  • namestringrequired
  • contentstring (base64)required
  • contentTypestring
  • contentIdstring or null
• tagstring or null

  A label of up to 100 characters, returned with the message and its events.

• metadatamap of string to stringdefault {}

  Up to 20 key-value pairs of your own, returned with the message and its events.

{
  "from": {
    "email": "no-reply@example.se",
    "name": "Example AB"
  },
  "to": [
    "anna@example.com"
  ],
  "subject": "Your invoice for September",
  "text": "Hi Anna, your invoice is attached.",
  "attachments": [
    {
      "name": "invoice.pdf",
      "content": "JVBERi0xLjcK",
      "contentType": "application/pdf"
    }
  ],
  "tag": "invoice",
  "metadata": {
    "invoiceId": "2026-0912"
  }
}

Responses

{
  "messageId": "5f432ffd-c005-499b-aa3a-5b8a088ea20e",
  "status": "accepted",
  "submittedAt": "2026-09-15T12:00:00.000Z",
  "test": false
}

Errors

Every error answers error, the code, and message, a sentence for a person. A code that adds fields is shown in full below the table.

• Retry-Afterheader on 429integer

  With rate_limited, the seconds until a send is accepted; absent with monthly_cap_reached.

• Retry-Afterheader on 503integer

  Seconds to wait before trying again.

{
  "error": "invalid_request",
  "message": "The request is invalid: to.0: Invalid email address",
  "issues": [
    {
      "path": "to.0",
      "message": "Invalid email address"
    }
  ]
}

{
  "error": "recipient_suppressed",
  "message": "One or more recipients are on the suppression list of this stream; suppressed says which and why.",
  "streamId": "3d1a2b4c-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "suppressed": [
    {
      "address": "anna@example.com",
      "reason": "hard_bounce"
    }
  ]
}

{
  "error": "test_address_on_live_server",
  "message": "Addresses at simulator.sendora.se act out an outcome on a test server and are never sent to from a live one. Send them from a test server.",
  "addresses": [
    "hardbounce@simulator.sendora.se"
  ]
}

{
  "error": "rate_limited",
  "message": "This server may send 60 emails per minute. Try again in 12 seconds.",
  "scope": "server",
  "limit": 60,
  "retryAfter": 12
}

{
  "error": "monthly_cap_reached",
  "message": "This account has used 50000 of 50000 emails this month. The cap resets at 2026-11-01T00:00:00.000Z.",
  "scope": "account",
  "cap": 50000,
  "used": 50000,
  "resetsAt": "2026-11-01T00:00:00.000Z"
}