Node.js (@frontmail/node)

@frontmail/node je určené pro servery, serverless funkce a skripty. Autentizuje se private key, takže se neuplatňují kontroly originu ani Turnstile, a zpřístupňuje hromadné odesílání, historii a schémata šablon.

npm install @frontmail/node

Vyžaduje Node.js 20+ (používá vestavěný fetch). Funguje také v Bunu, Denu a edge runtimech, které fetch poskytují.

Vytvoření klienta

import { Frontmail } from '@frontmail/node';

const frontmail = new Frontmail({
  privateKey: process.env.FRONTMAIL_PRIVATE_KEY!, // sk_…
  // retry: { retries: 3 }, timeoutMs: 15_000, apiUrl: 'https://api.frontmail.dev'
});

Bez privateKey si klient načte FRONTMAIL_PRIVATE_KEY (a FRONTMAIL_API_URL) z proměnných prostředí. Private key nikdy nevystavujte v bundlu pro prohlížeč – držte ho v proměnných prostředí nebo ve správci tajemství. Viz Public a private klíče.

Ve webovém prohlížeči balíček odmítne běžet: při importu vypíše varování a new Frontmail() vyhodí private_key_in_browser (vypnout to jde volbou dangerouslyAllowPrivateKeyInBrowser: true, ale jen pro interní nástroje na důvěryhodných počítačích). V prohlížeči použijte @frontmail/browser s veřejným klíčem.

Odeslání

const result = await frontmail.send({
  serviceId: 'svc_01J9…', // volitelné – bez něj se použije výchozí služba
  templateId: 'tpl_order',
  params: {
    order_id: 'A-1042',
    items: [{ title: 'Pokoj', qty: 2, price: 89 }],
    total: 178,
    currency: 'EUR',
  },
});
console.log(result.messageId, result.status); // 'queued' | 'held'

Další pole vstupu: idempotencyKey (doporučeno, pokud odeslání spouští něco, co se může opakovat, např. webhook – použijte ID jeho události), attachments, signal.

Hromadné odeslání

Pošlete až 100 zpráv v jednom požadavku. Každá zpráva se validuje a účtuje samostatně – jedna neplatná zpráva neshodí ostatní. sendBatch kvůli chybám jednotlivých zpráv nevyhazuje výjimku; u každého výsledku zkontrolujte ok.

const results = await frontmail.sendBatch([
  { serviceId: 'svc_01J9…', templateId: 'tpl_reminder', params: { name: 'Jana' }, idempotencyKey: 'reminder-42-jana' },
  { serviceId: 'svc_01J9…', templateId: 'tpl_reminder', params: { name: 'Petr' }, idempotencyKey: 'reminder-42-petr' },
]);

for (const r of results) {
  if (!r.ok) console.error(r.index, r.error.code);
  else console.log(r.index, r.messageId, r.status);
}

Pro rate limity se dávka počítá jako jeden požadavek. Více než 100 zpráv rozdělte do několika dávek.

Historie

const page = await frontmail.history({
  status: 'failed',
  templateId: 'tpl_order',
  from: '2026-09-01T00:00:00Z',
  limit: 50,
});

for (const m of page.items) console.log(m.messageId, m.status, m.to, m.subject);

// Další stránka
if (page.nextCursor) await frontmail.history({ cursor: page.nextCursor });

// Nebo projděte všechno
for await (const m of frontmail.history({ status: 'bounced' })) console.log(m.to);

Filtry: status, templateId, serviceId, from, to, q (hledání podle příjemce), limit (≤ 100), cursor. await history() vrátí jednu stránku; for await postupně projde všechny stránky. Historie pokrývá dobu uchovávání dat podle vašeho tarifu.

Stav zprávy

const msg = await frontmail.getMessage('msg_01J9Z3K7Q2');
// { messageId, status, createdAt, sentAt, templateId, serviceId, events: [{ type, at }, …] }

Šablony

const templates = await frontmail.templates.list(); // schémata parametrů, používá je `frontmail types`
const contact = await frontmail.templates.get('tpl_contact');

CLI

Balíček obsahuje CLI frontmail – viz Typované parametry.

Ukázkový projekt: examples/node.