Skip to content
Frontmail Docs

Overview and concepts

Frontmail lets you send email straight from your frontend – a contact form, a booking request, an order confirmation – without running your own backend. You connect the email provider you already use, design an HTML template with typed parameters in the dashboard, and call one function:

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


init({ publicKey: 'pk_4f2a…' });
await send('svc_01J9…', 'tpl_01J9…', { name: 'Jana', message: 'Hello!' });

The request goes to the Frontmail API, which checks it (origin, bot protection, rate limits, parameter validation), reserves one credit and queues the email. A sender then renders the template and delivers it through your provider. Delivery events (delivered, bounced, opened…) flow back through provider webhooks into your history and statistics.

The building blocks

Section titled “The building blocks”

Organization

Section titled “Organization”

Everything – keys, services, templates, credits, members – belongs to an organization. One user can be a member of several organizations and switch between them. Each organization has a plan and its own credit balance.

Public key and private key

Section titled “Public key and private key”
Public key pk_… Private key sk_…
Where it lives In your frontend code – it is not a secret On your server only – treat it like a password
How it’s sent user_id in the body or X-Frontmail-Public-Key header Authorization: Bearer sk_… (or accessToken in the body) – never from a browser: requests with an Origin header are refused
Protected by Allowed origins, Turnstile, rate limits, bot protection Its secrecy – it skips origin and CAPTCHA checks
Can do send, send-form, uploads, read status of its own messages Everything above plus send-batch, history, templates

Because a public key is visible to anyone who opens your page, Frontmail never trusts it alone. Read Public and private keys before going live.

Services

Section titled “Services”

A service is a connection to an email provider: SMTP (Seznam, Zoho, your own server), Mailgun, Amazon SES, Postmark, SendGrid, Mailjet, Brevo, Resend, Gmail or Outlook / Microsoft 365. Credentials are encrypted with AWS KMS. Frontmail checks every service daily and immediately after an authentication error, and a template can have a fallback service that takes over when the primary one fails. See Services overview.

Templates

Section titled “Templates”

A template is a full HTML email (with a generated plain-text version) plus subject, recipients (To, CC, BCC, Reply-To, From) and a parameter schema. Parameters are typed (string, email, number, date, list…) and validated on every send, and the body uses Handlebars for conditions, loops and formatting helpers. See HTML templates and Parameters and types.

Credits

Section titled “Credits”

One accepted email = one credit. Credits come from grants:

  • subscription – your monthly plan quota (does not roll over),
  • pack – prepaid credit packs valid for 3–12 months, available on every plan including Free,
  • bonus – credits added by Frontmail support,
  • overdraft – a 10 % buffer on paid plans, billed on your next invoice.

Credits are always taken from the grant that expires first, overdraft last. Test sends from the template editor are free. If a send fails permanently, the credit is refunded. See Consumption order.

No email is silently dropped

Section titled “No email is silently dropped”

When you run out of credits, Frontmail does not throw your email away. In the default hold mode it accepts the request with 202 { "status": "held" }, stores the message and sends it automatically as soon as credits are available again – after a pack purchase, an auto top-up, an upgrade or the next billing period. Read Hold queue.

Message lifecycle

Section titled “Message lifecycle”
accepted ─┬─► queued ─► sending ─► sent ─┬─► delivered
          │                              ├─► bounced
          │                              └─► complained
          ├─► held (no credits) ─► queued …   or ─► discarded (hold expired / manual)
          └─► (on provider auth error) held_service_error ─► queued … after the service is fixed
                                     failed (permanent error, credit refunded)

All statuses are explained in Message statuses.

Next steps

Section titled “Next steps”