Vanilla JavaScript (@frontmail/browser)

@frontmail/browser je drobné SDK (< 3,5 kB po gzipe) bez závislostí, použiteľné na akomkoľvek webe. Jeho API kopíruje @emailjs/browser, takže existujúci kód potrebuje len pár úprav.

Inštalácia

npm
CDN (script tag)

npm install @frontmail/browser

import { init, send, sendForm, getStatus } from '@frontmail/browser';

<script
  src="https://cdn.jsdelivr.net/npm/@frontmail/browser@0.1.0/dist/frontmail.umd.js"
  integrity="sha384-g2Rxznkz2yb/YYSdVTkXLxZFZ2Nh2+XdhPStxh0stydXFF3gYjDuyHimWIZLJDCc"
  crossorigin="anonymous"></script>
<script>
  frontmail.init({ publicKey: 'pk_4f2a…' });
</script>

UMD build sprístupňuje globálny objekt frontmail s funkciami init, send, sendForm, getStatus a triedami chýb. Vždy načítavajte konkrétnu verziu so Subresource Integrity – pozrite Pripnutie verzie nižšie.

init(options)

Zavolajte raz, ešte pred odosielaním:

init({
  publicKey: 'pk_4f2a…',
  blockHeadless: true,                                   // voliteľné, pozrite Ochrana pred botmi
  blockList: { list: ['spam@example.net'], watchVariable: 'email' },
  limitRate: { id: 'contact', throttle: 10_000 },        // najviac jedno odoslanie za 10 s
  retry: { retries: 3, baseDelayMs: 300 },               // predvolené; `false` opakovanie vypne
  timeoutMs: 15_000,                                     // na jeden pokus
  apiUrl: 'https://api.frontmail.dev',                   // predvolené
});

Funguje aj init('pk_4f2a…') len s reťazcom kľúča.

send(serviceId, templateId, params?, options?)

const result = await send('svc_01J9…', 'tpl_order', {
  name: 'Jana',
  items: [{ title: 'Izba', qty: 2, price: 89 }],
});
// { messageId: 'msg_…', status: 'queued' | 'held', statusToken: '…', status_code: 202, text: 'OK' }

serviceId môže byť null – potom sa použije predvolená služba organizácie.
params sa na serveri validujú voči schéme šablóny.
options prijíma turnstileToken, attachments, idempotencyKey, locale, signal (AbortSignal), publicKey pre konkrétne volanie a ochrany pre konkrétne volanie (blockHeadless, blockList, limitRate). Samotný reťazec sa berie ako verejný kľúč, rovnako ako v EmailJS.
locale (napr. 'de') vyberie jazyk šablóny; pri neznámom jazyku sa použije rovnaký základný jazyk a potom predvolený jazyk. result.locale je jazyk, v ktorom e-mail odišiel.

Promise sa resolvne pre queued aj held – pozdržaná správa je prijatá a odíde, keď budú k dispozícii kredity (pozrite Fronta pozdržaných e-mailov). V ostatných prípadoch sa rejectne s typovanou chybou (pozrite Spracovanie chýb).

sendForm(serviceId, templateId, form, options?)

<form id="contact">
  <input name="name" required>
  <input name="email" type="email" required>
  <textarea name="message"></textarea>
  <input type="file" name="attachment">
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button>Odoslať</button>
</form>
<script type="module">
  import { init, sendForm } from '@frontmail/browser';
  init({ publicKey: 'pk_4f2a…' });

  document.getElementById('contact').addEventListener('submit', async (event) => {
    event.preventDefault();
    const { status } = await sendForm('svc_01J9…', 'tpl_contact', event.target);
    // alebo: sendForm('svc_01J9…', 'tpl_contact', '#contact')
  });
</script>

Formulár sa odošle ako multipart/form-data. Z textových polí sa stanú parametre (prevedú sa na deklarované typy), zo súborových polí prílohy a token Turnstile v cf-turnstile-response sa prevezme automaticky. Použite site key svojho vlastného widgetu Turnstile – pozrite Cloudflare Turnstile.

Polia, ktoré nemajú opustiť váš web, sa preskočia: heslá (type="password"), anti-CSRF polia bežných frameworkov (csrfmiddlewaretoken, _token, authenticity_token, __RequestVerificationToken, _csrf, csrf_token) a rezervované názvy API (accessToken, privateKey, turnstile_key, …). Odosielané polia si môžete vybrať sami voľbou formFields:

await sendForm('svc_01J9…', 'tpl_contact', '#contact', {
  formFields: { include: ['name', 'email', 'message'] }, // len tieto (+ token Turnstile)
  // alebo: formFields: { exclude: ['internal_note'] }
});

Ak chcete formulár poslať v niektorom jazyku šablóny, odovzdajte { locale: 'de' } – pošle sa ako vyhradené pole fm_locale – alebo pridajte pole fm_locale do formulára sami (napr. výber jazyka <select name="fm_locale">); pole formulára má prednosť. Pole s názvom locale zostáva bežným parametrom šablóny.

getStatus(messageId, options)

const status = await getStatus(result.messageId, { token: result.statusToken });
// { messageId, status: 'sent', createdAt, sentAt, templateId, serviceId, events: [...] }

S verejným kľúčom môžete čítať len správy, ktoré ste sami odoslali, a to pomocou statusToken z výsledku odoslania. SDK ho posiela v hlavičke X-Frontmail-Status-Token (nie v URL, takže nekončí v logoch). Pozrite Stavy správ.

Pripnutie verzie a Subresource Integrity

Tag <script> má plný prístup k vašej stránke. Načítavajte konkrétnu verziu a nechajte prehliadač overiť jej hash – zmenený súbor (napadnuté CDN alebo vydanie) potom prehliadač odmietne namiesto toho, aby ho spustil:

<script
  src="https://cdn.jsdelivr.net/npm/@frontmail/browser@0.1.0/dist/frontmail.umd.js"
  integrity="sha384-g2Rxznkz2yb/YYSdVTkXLxZFZ2Nh2+XdhPStxh0stydXFF3gYjDuyHimWIZLJDCc"
  crossorigin="anonymous"></script>

jsDelivr (npm): hash každého vydania nájdete v poznámkach k vydaniu na GitHube (a pod tlačidlom „Copy HTML + SRI“ na jsDelivr).
CDN Frontmailu: https://cdn.frontmail.dev/v<verzia>/frontmail.umd.js; hodnota integrity je v https://cdn.frontmail.dev/v<verzia>/sri.json.
Pri aktualizácii zmeňte verziu aj hash súčasne (pozrite changelog).

Content Security Policy

Ak váš web používa CSP, povoľte:

connect-src https://api.frontmail.dev;
script-src https://cdn.jsdelivr.net https://challenges.cloudflare.com;   # CDN build (alebo cdn.frontmail.dev), Turnstile
frame-src https://challenges.cloudflare.com;                              # Turnstile