Idempotency keys

Retry a send safely. The same key and body never send twice.

A request can time out after Notix has already sent the email. If your code retries, the customer gets two receipts. An idempotency key stops that. Send the same key with the same body and Notix answers with the first result instead of sending again.

Add a key

Send an Idempotency-Key header of up to 256 characters. It works on Send an email, Send a batch of emails and Send an SMS.

curl -X POST https://app.usenotix.dev/api/v1/emails \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Idempotency-Key: order-4471-receipt" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <receipts@acme.com>",
    "to": "customer@example.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>",
  },
  { idempotencyKey: "order-4471-receipt" },
);

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

data, error = 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>",
    },
    {"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>',
], 'order-4471-receipt');

What happens on a retry

You send	Notix answers
The same key and the same body	`200` with the original `emailId`, and the header `Idempotent-Replayed: true`. Nothing is sent again.
The same key and a different body	`409` with code `NOT_UNIQUE`. Nothing is sent.
The same key while the first request is still running	`409`. Wait a moment and retry.
The same key after a request that stopped part way	`409` with code `PARTIAL_COMPLETION`, listing the email ids already sent. Nothing is sent again.

Keys last 24 hours. After that, the same key is treated as new.

Keys belong to the API key that sent them. Two services with different API keys never share a key, even if they pick the same string.

Pick a good key

Build the key from your own record, so the same event always makes the same key.

Good: order-4471-receipt, signup-ada@example.com-welcome, invoice-INV-2026-0142.
Bad: a random value made fresh on each retry, or retry-3. A new key on every retry sends a new email every time.

Use one key per message you mean to send once. If you send a receipt and a shipping notice for the same order, give them different keys.

Retry the right errors

Retry network errors, timeouts, 429 and 5xx answers, with a growing wait between tries. Keep the same key and body each time.

Do not retry 400, 401, 403 or 422. The request itself is wrong, and sending it again will not change the answer.

See Errors for every code, and Idempotency in the API reference.

Open in Claude Open in ChatGPT