Vanilla JavaScript (@frontmail/browser)

@frontmail/browser je malinké SDK (< 3,5 kB po gzipu) bez závislostí, použitelné na jakémkoli webu. Jeho API kopíruje @emailjs/browser, takže stávající kód potřebuje jen pár úprav.

Instalace

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 vystavuje globální objekt frontmail s funkcemi init, send, sendForm, getStatus a třídami chyb. Vždy načítejte konkrétní verzi se Subresource Integrity – viz Připnutí verze níže.

init(options)

Zavolejte jednou, ještě před odesíláním:

init({
  publicKey: 'pk_4f2a…',
  blockHeadless: true,                                   // volitelné, viz Ochrana proti botům
  blockList: { list: ['spam@example.net'], watchVariable: 'email' },
  limitRate: { id: 'contact', throttle: 10_000 },        // nejvýše jedno odeslání za 10 s
  retry: { retries: 3, baseDelayMs: 300 },               // výchozí; `false` retry vypne
  timeoutMs: 15_000,                                     // na jeden pokus
  apiUrl: 'https://api.frontmail.dev',                   // výchozí
});

Funguje i init('pk_4f2a…') jen s řetězcem klíče.

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

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

serviceId může být null – pak se použije výchozí služba organizace.
params se na serveru validují proti schématu šablony.
options přijímá turnstileToken, attachments, idempotencyKey, signal (AbortSignal), publicKey pro konkrétní volání a ochrany pro konkrétní volání (blockHeadless, blockList, limitRate). Samotný řetězec se bere jako public key, stejně jako v EmailJS.

Promise se resolvne pro queued i held – zadržená zpráva je přijatá a odejde, jakmile budou k dispozici kredity (viz Fronta zadržených zpráv). V ostatních případech se rejectne s typovanou chybou (viz Zpracování chyb).

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>Odeslat</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);
    // nebo: sendForm('svc_01J9…', 'tpl_contact', '#contact')
  });
</script>

Formulář se odešle jako multipart/form-data. Textová pole se stanou parametry (převedou se na deklarované typy), souborová pole se stanou přílohami a Turnstile token v cf-turnstile-response se převezme automaticky. Použijte site key svého vlastního widgetu Turnstile – viz Cloudflare Turnstile.

Pole, která nemají opustit váš web, se přeskočí: hesla (type="password"), anti-CSRF pole běžných frameworků (csrfmiddlewaretoken, _token, authenticity_token, __RequestVerificationToken, _csrf, csrf_token) a rezervované názvy API (accessToken, privateKey, turnstile_key, …). Odesílaná pole si můžete vybrat sami volbou formFields:

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

getStatus(messageId, options)

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

S public key můžete číst jen zprávy, které jste sami odeslali, a to pomocí statusToken z výsledku odeslání. SDK ho posílá v hlavičce X-Frontmail-Status-Token (ne v URL, takže nekončí v logech). Viz Stavy zpráv.

Připnutí verze a Subresource Integrity

Tag <script> má plný přístup k vaší stránce. Načítejte konkrétní verzi a nechte prohlížeč ověřit její hash – změněný soubor (napadené CDN nebo vydání) pak prohlížeč odmítne, místo 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 vydání najdete v poznámkách k vydání na GitHubu (a pod tlačítkem „Copy HTML + SRI“ na jsDelivr).
CDN Frontmailu: https://cdn.frontmail.dev/v<verze>/frontmail.umd.js; hodnota integrity je v https://cdn.frontmail.dev/v<verze>/sri.json.
Při aktualizaci změňte verzi i hash současně (viz changelog).

Content Security Policy

Pokud váš web používá CSP, povolte:

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