Send an email

Send one transactional email.

POSThttps://app.usenotix.dev/api/v1/emails

Full access and sending access keys can call this. Key permissions lists the extra rules some calls have.

Send one transactional email. The response carries the emailId every webhook event for the message refers to.

Limits

Every send request is bounded. The checks run before the email is stored, so a request that breaks one of them costs nothing and creates nothing.

Field	Limit
Request body	20 MB, applied at the edge
`to`, `cc`, `bcc`	50 recipients across the three fields, counted on distinct addresses
`subject`	998 characters
`html`	2,000,000 characters
`text`	2,000,000 characters
`attachments`	10 files
`attachments[].filename`	255 characters
`attachments[].content`	7 MB per file, once decoded from base64
`attachments` total	10 MB per email, once decoded from base64

Attachment sizes are measured after base64 decoding, so a 7 MB file is about 9.4 MB of base64 in the request body.

Recipients

to, cc and bcc each take a single address or an array of them, and the three together may name at most 50 distinct recipients. The same address in two fields is one recipient: addresses are compared case insensitively, and a display-name form (Ada Lovelace <ada@example.com>) is compared on the address inside it.

Every recipient counts as one email against the team's daily and monthly send limits and on the bill. A recipient on the team's suppression list is not sent to and is not counted. A message naming more than 50 is refused with 422 before anything is sent:

json

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "A message can name at most 50 recipients across to, cc and bcc; this one names 63."
  }
}

Errors

Status	Code	Meaning
400	`BAD_REQUEST`	The request is invalid, including any size limit above. The body names the field and the limit.
401	`UNAUTHORIZED`	The API key is missing or not valid.
403	`FORBIDDEN`	The API key is restricted to a domain other than the `from` address.
413		The request body is over 20 MB. It is refused at the edge, with no JSON body.
422	`UNPROCESSABLE_ENTITY`	The message names more than 50 recipients across `to`, `cc` and `bcc`.
429	`RATE_LIMITED`	The per second rate limit or the team's send limit was reached.

Idempotency

Pass an Idempotency-Key header to make a retry safe for 24 hours. The same key and body answers the original result without sending again, with the response header Idempotent-Replayed: true. The same key with a different body answers 409 NOT_UNIQUE; the same key while the first request is still running answers 409 too, so retry shortly. Keys are scoped to the API key.

Dry run

Send the header Notix-Dry-Run: true to see what the request would do without doing it. The answer is 200 with dryRun: true: who it would reach, what they would see, what it would cost, a verdict (allowed and every reasons it would be refused for) and the limits it would count against. Nothing is sent, charged, reserved or written, and the call is recorded in the audit log as a dry run. A write route that cannot preview answers 400.

Body parameters

tostring or string[]

The visible recipients. Optional when cc or bcc names somebody, which is how a Bcc-only message is sent. At most 50 distinct addresses across to, cc and bcc, and every one of them counts as an email against the team's quota.

fromstringrequired

subjectstring

Optional when templateId is provided. At most 998 characters.

At most 998 characters.

templateIdstring

ID of a template from the dashboard. A template carries its own subject, preview text and type (transactional or marketing); pass variables to fill it. A link that is exactly one variable, such as {{actionUrl}}, is only filled with an http(s), mailto or tel address.

variablesmap of string

Values for the template's variables: at most 200, each at most 10000 characters.

replyTostring or string[]

ccstring or string[]

Copied recipients. Counted with to and bcc against the 50 recipient cap and against the team's quota.

bccstring or string[]

Blind copied recipients. Counted with to and cc against the 50 recipient cap and against the team's quota.

textstring

Plain text body. At most 2,000,000 characters.

At most 2,000,000 characters. Can be null.

htmlstring

HTML body. At most 2,000,000 characters.

At most 2,000,000 characters. Can be null.

headersmap of string

Custom headers to include with the email: at most 50, each name at most 100 characters and each value at most 2,000. A name must be a plain header name (letters, digits and - ; no spaces, colons or control characters) and a value may not contain control characters such as line breaks; either answers 400. Identity and trace headers (From, Sender, Reply-To, Return-Path, Message-ID, DKIM-Signature, ARC-*, Authentication-Results, Received and similar) are set by Notix and are dropped if sent here.

attachmentsobject[]

Up to 10 files, each at most 7 MB decoded, and at most 10 MB decoded in total.

attachments[].filenamestringrequired

At most 255 characters.

attachments[].contentstringrequired

scheduledAtstring (date-time)

inReplyToIdstring

Can be null.

Headers

Authorizationstringrequired

Bearer followed by your API key.

Idempotency-Keystring

Pass the optional Idempotency-Key header to make the request safe to retry. The key can be up to 256 characters. The server stores the canonical request body and behaves as follows: - Same key + same request body → returns the original emailId with 200 OK without re-sending, and the response header Idempotent-Replayed: true. - Same key + different request body → returns 409 Conflict with code: NOT_UNIQUE so you can detect the mismatch. - Same key while another request is still being processed → returns 409 Conflict; retry after a short delay or once the first request completes. Entries expire after 24 hours. Use a unique key per logical send (for example, an order or signup ID).

Notix-Dry-Runstring

Set to true to preview the request instead of running it. The answer is 200 with dryRun: true: who it would reach, what they would see, what it would cost, whether policy allows it and the limits it counts against. Nothing is sent, charged, reserved or written. A write route that cannot preview answers 400.

Errors

422

The message names more than 50 distinct recipients across to, cc and bcc.

Every error has the same shape. See all error codes.

curl -X POST "https://app.usenotix.dev/api/v1/emails" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "from": "Acme <receipts@acme.com>",
  "subject": "Your receipt for order 4471",
  "html": "<p>Thanks for your order.</p>"
}'

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.emails.send(
  {
    from: "Acme <receipts@acme.com>",
    to: "customer@example.com",
    subject: "Your receipt for order 4471",
    html: "<p>Thanks for your order.</p>",
    text: "Thanks for your order.",
  },
  { idempotencyKey: "order-4471-receipt" },
);

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

data, _ = notix.emails.send(
    {
        "from": "Acme <receipts@acme.com>",
        "to": "customer@example.com",
        "subject": "Your receipt for order 4471",
        "html": "<p>Thanks for your order.</p>",
        "text": "Thanks for your order.",
    },
    {"idempotency_key": "order-4471-receipt"},
)

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$email = $notix->emails->send([
    'from' => 'Acme <receipts@acme.com>',
    'to' => 'customer@example.com',
    'subject' => 'Your receipt for order 4471',
    'html' => '<p>Thanks for your order.</p>',
    'text' => 'Thanks for your order.',
], 'order-4471-receipt');

Response200

{
  "emailId": "cm1x8f3k20001qz7v5b9d2e4a"
}

Open in Claude Open in ChatGPT