Integrations

Send and track email from an Express server.

An Express app needs three things from Notix: a client created once at startup, a route that sends, and a webhook route that proves each delivery event came from Notix. The one Express-specific trap is the body parser, which has to stay off the webhook route.

The send

Send an email from Express.

server.ts

import express from "express";
import { Notix } from "notix-js";

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

app.post("/orders/:id/receipt", express.json(), async (req, res) => {
  const { data, error } = await notix.emails.send(
    { from: "Acme <receipts@acme.com>", to: req.body.email, subject: "Your receipt", html: "<p>Thanks.</p>" },
    { idempotencyKey: `order-${req.params.id}-receipt` },
  );
  if (error) return res.status(502).json({ error });
  res.json({ id: data?.emailId });
});

app.listen(3000);

The same request from a terminal

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

The from address must be on a domain you have verified in Notix. Step by step: the Node.js quickstart and the longer guide to sending email from Express.

Environment

One API key, kept on the server.

Create an API key on the API keys page of the Notix console and store it as NOTIX_API_KEY in the process environment (a .env file loaded at startup works). Read it only in code that runs on the server, never in anything shipped to a browser.

A Send only key is enough for code that only sends: if it leaks, it cannot read your contacts or delete a domain.

.env

NOTIX_API_KEY=notix_xxxxxxxxxxxx
NOTIX_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Webhooks

Verify delivery events over the raw body.

Notix signs every webhook call with the webhook's signing secret: an HMAC-SHA256 of the X-Notix-Timestamp header, a dot and the raw body, sent in X-Notix-Signature. The SDKs check the signature and refuse a call more than 5 minutes old.

Mount express.raw on the webhook route, not express.json: a parsed and re-serialised body no longer matches the signature.

express.raw keeps the body as bytes

app.post("/webhooks/notix", express.raw({ type: "application/json" }), (req, res) => {
  const webhooks = notix.webhooks(process.env.NOTIX_WEBHOOK_SECRET!);
  try {
    const event = webhooks.constructEvent(req.body.toString("utf8"), { headers: req.headers });
    if (event.type === "email.bounced") {
      // Mark the address in your own records.
    }
    res.send("ok");
  } catch {
    res.status(400).send("invalid signature");
  }
});

FAQ

Questions, answered.

Why does my webhook signature check fail in Express?

Usually because express.json() ran first and the handler is verifying a re-serialised body. Register the webhook route with express.raw({ type: 'application/json' }) and pass the raw bytes to constructEvent.

What if the same request runs twice?

Send an Idempotency-Key header (idempotencyKey in notix-js) with a value that names the thing being sent, such as order-4471-receipt. A repeat with the same key and body returns the first result and sends nothing new; the same key with a different body is refused with 409.

Why is my send refused with a from-address error?

The from address must be on a domain you have verified in Notix. Add the domain in the console, publish the DNS records it shows, and wait for verification; until then, sends from that domain are refused.

The free plan does not ask for a card.

Guides