Order confirmations and receipts that send exactly once.

# One template, tpl_order_confirmation, with variables for the order.
# The idempotency key names the order and the purpose, so a retried call
# after a timeout returns the original emailId instead of a second email.
curl -X POST https://app.usenotix.dev/api/v1/emails \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Idempotency-Key: order-48213-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": "chidi@example.com",
    "replyTo": "support@acme.com",
    "templateId": "tpl_order_confirmation",
    "variables": {
      "orderNumber": "48213",
      "customerName": "Chidi",
      "items": "2 x Desk lamp (NGN 24,000), 1 x Bulb pack (NGN 3,500)",
      "total": "NGN 27,500",
      "deliveryDate": "Thursday 18 September",
      "orderUrl": "https://acme.com/orders/48213"
    }
  }'

# 200 { "emailId": "eml_abc123" }
# Same key, same body again: 200 with the same emailId, no second email.
# Same key, different body: 409 NOT_UNIQUE.

import { Notix } from "notix-js";

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

// Called from the payment provider's success webhook, never from the checkout page.
export async function sendOrderConfirmation(orderId: string) {
  const order = await db.order.findUniqueOrThrow({
    where: { id: orderId },
    include: { items: true, customer: true },
  });

  const { data, error } = await notix.emails.send(
    {
      from: "Acme <orders@acme.com>",
      to: order.customer.email,
      replyTo: "support@acme.com",
      templateId: "tpl_order_confirmation",
      variables: {
        orderNumber: order.number,
        customerName: order.customer.firstName,
        // Variables are strings: format the line items and the total here.
        items: order.items
          .map((i) => `${i.qty} x ${i.name} (${formatMoney(i.priceMinor, order.currency)})`)
          .join(", "),
        total: formatMoney(order.totalMinor, order.currency),
        deliveryDate: formatDate(order.deliveryDate),
        orderUrl: `https://acme.com/orders/${order.number}`,
      },
    },
    // The order id and the purpose. A receipt for the same order gets a
    // different key: order-${order.id}-receipt.
    { idempotencyKey: `order-${order.id}-confirmation` },
  );

  if (error) {
    // 409 NOT_UNIQUE means this key was already used with a different body:
    // the order changed after the first send. Everything else is worth a retry.
    throw new Error(`confirmation failed: ${error.code} ${error.message}`);
  }

  // Keep the id on the order so support can see what happened to it.
  await db.order.update({ where: { id: order.id }, data: { confirmationEmailId: data.emailId } });
}

import os

from notix import Notix

notix = Notix(os.environ["NOTIX_API_KEY"])


# Called from the payment provider's success webhook, never from the checkout page.
def send_order_confirmation(order_id: str) -> None:
    order = db.orders.get(order_id, include=["items", "customer"])

    data, error = notix.emails.send(
        payload={
            "from": "Acme <orders@acme.com>",
            "to": order.customer.email,
            "replyTo": "support@acme.com",
            "templateId": "tpl_order_confirmation",
            "variables": {
                "orderNumber": order.number,
                "customerName": order.customer.first_name,
                # Variables are strings: format the line items and the total here.
                "items": ", ".join(
                    f"{i.qty} x {i.name} ({format_money(i.price_minor, order.currency)})"
                    for i in order.items
                ),
                "total": format_money(order.total_minor, order.currency),
                "deliveryDate": format_date(order.delivery_date),
                "orderUrl": f"https://acme.com/orders/{order.number}",
            },
        },
        # The order id and the purpose. A receipt for the same order gets a
        # different key: order-{order.id}-receipt.
        options={"idempotency_key": f"order-{order.id}-confirmation"},
    )

    if error:
        # 409 NOT_UNIQUE means this key was already used with a different body:
        # the order changed after the first send. Everything else is worth a retry.
        raise RuntimeError(f"confirmation failed: {error['code']} {error['message']}")

    # Keep the id on the order so support can see what happened to it.
    db.orders.update(order.id, confirmation_email_id=data["emailId"])

// POST /hooks/notix  (Express: app.post("/hooks/notix", express.raw({ type: "*/*" }), handler))
import { Notix } from "notix-js";

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

export async function handler(req, res) {
  // Verifies X-Notix-Signature over the timestamp and the raw body, with a
  // five-minute tolerance. Throws on a bad or stale signature.
  const event = webhooks.constructEvent(req.body, req.headers);
  res.status(200).end(); // acknowledge first, then work

  const order = await db.order.findFirst({ where: { confirmationEmailId: event.data.id } });
  if (!order) return;

  switch (event.type) {
    case "email.delivered":
      await db.order.update({ where: { id: order.id }, data: { confirmationStatus: "sent" } });
      break;
    case "email.bounced":
      // Permanent: the address is now suppressed; ask the customer for another one.
      // Transient: the mailbox was full or the server was busy; nothing to do yet.
      if (event.data.bounce.type === "Permanent") {
        await db.order.update({ where: { id: order.id }, data: { confirmationStatus: "address_invalid" } });
        await flagOrderForContact(order.id);
      }
      break;
    case "email.complained":
      // A receipt marked as spam is rare; do not resend it.
      await db.order.update({ where: { id: order.id }, data: { confirmationStatus: "complained" } });
      break;
  }
}

# POST /hooks/notix  (Flask: use request.get_data() for the raw body)
import os

from notix import Notix

notix = Notix(os.environ["NOTIX_API_KEY"])
webhooks = notix.webhooks(os.environ["NOTIX_WEBHOOK_SECRET"])


@app.post("/hooks/notix")
def notix_hook():
    # Verifies X-Notix-Signature over the timestamp and the raw body, with a
    # five-minute tolerance. Raises on a bad or stale signature.
    event = webhooks.construct_event(request.get_data(), request.headers)
    queue.enqueue(handle_event, event)  # acknowledge first, then work
    return "", 200


def handle_event(event: dict) -> None:
    order = db.orders.find_by_confirmation_email_id(event["data"]["id"])
    if order is None:
        return

    if event["type"] == "email.delivered":
        db.orders.update(order.id, confirmation_status="sent")
    elif event["type"] == "email.bounced":
        # Permanent: the address is now suppressed; ask the customer for another one.
        if event["data"]["bounce"]["type"] == "Permanent":
            db.orders.update(order.id, confirmation_status="address_invalid")
            flag_order_for_contact(order.id)
    elif event["type"] == "email.complained":
        # A receipt marked as spam is rare; do not resend it.
        db.orders.update(order.id, confirmation_status="complained")