Node.js (@frontmail/node)

@frontmail/node je určené pre servery, serverless funkcie a skripty. Autentifikuje sa súkromným kľúčom, takže sa neuplatňujú kontroly originu ani Turnstile, a sprístupňuje hromadné odosielanie, históriu a schémy šablón.

npm install @frontmail/node

Vyžaduje Node.js 20+ (používa vstavaný fetch). Funguje aj v Bune, Dene a edge runtimoch, ktoré fetch poskytujú.

Vytvorenie 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číta FRONTMAIL_PRIVATE_KEY (a FRONTMAIL_API_URL) z premenných prostredia. Súkromný kľúč nikdy nevystavujte v bundli pre prehliadač – držte ho v premenných prostredia alebo v správcovi tajomstiev. Pozrite Verejný a súkromný kľúč.

Vo webovom prehliadači balík odmietne bežať: pri importe vypíše varovanie a new Frontmail() vyhodí private_key_in_browser (vypnúť sa to dá voľbou dangerouslyAllowPrivateKeyInBrowser: true, ale len pre interné nástroje na dôveryhodných počítačoch). V prehliadači použite @frontmail/browser s verejným kľúčom.

Odoslanie

const result = await frontmail.send({
  serviceId: 'svc_01J9…', // voliteľné – bez neho sa použije predvolená služba
  templateId: 'tpl_order',
  params: {
    order_id: 'A-1042',
    items: [{ title: 'Izba', qty: 2, price: 89 }],
    total: 178,
    currency: 'EUR',
  },
});
console.log(result.messageId, result.status); // 'queued' | 'held'

Ďalšie vstupné polia: idempotencyKey (odporúčané, ak odoslanie spúšťa niečo, čo sa môže opakovať, napr. webhook – použite ID jeho udalosti), attachments, locale, signal.

locale (napr. 'de') pošle e-mail v zadanom jazyku šablóny – presná zhoda, potom rovnaký základný jazyk (de-AT → de), inak predvolený jazyk. result.locale je použitý jazyk:

const { locale } = await frontmail.send({ templateId: 'tpl_order', params: { order_id: 'A-1042' }, locale: user.language });

Hromadné odosielanie

Pošlite až 100 správ v jednej požiadavke. Každá správa sa validuje a účtuje samostatne – jedna neplatná správa nezhodí ostatné. sendBatch pri chybách jednotlivých správ nevyhadzuje výnimku; pri každom výsledku skontrolujte 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);
}

Pre rate limity sa dávka počíta ako jedna požiadavka. Viac než 100 správ rozdeľte do niekoľkých dávok. Každá správa môže mať vlastné locale; úspešné výsledky obsahujú použité locale.

História

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);

// Ďalšia stránka
if (page.nextCursor) await frontmail.history({ cursor: page.nextCursor });

// Alebo prejdite všetko
for await (const m of frontmail.history({ status: 'bounced' })) console.log(m.to);

Filtre: status, templateId, serviceId, from, to, q (hľadanie podľa príjemcu), limit (≤ 100), cursor. await history() vráti jednu stránku; for await postupne prejde všetky stránky. História pokrýva dobu uchovávania údajov podľa vášho tarifu.

Stav správy

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

Šablóny

const templates = await frontmail.templates.list(); // schémy parametrov, používa ich `frontmail types`
const contact = await frontmail.templates.get('tpl_contact');
contact.locales; // ['en', 'de', 'pt-BR'] – najprv predvolený jazyk, potom preklady

frontmail types pridá jazyky každej šablóny do jej dokumentačného komentára a vygeneruje zjednotený typ pre voľbu locale:

/** Contact form (tpl_contact) – languages: en (default), de, pt-BR */
export interface ContactFormParams { /* … */ }
/** Languages of tpl_contact (default first) – for the `locale` send option. */
export type ContactFormLocale = "en" | "de" | "pt-BR";

CLI

Balík obsahuje CLI frontmail – pozrite Typované parametre.

Ukážkový projekt: examples/node.