Email

What this is

Email is how a site writes to someone. It is a platform capability, like People or Store. It is not a module and it is not a widget. Do not invent markup for a campaign. Do not enable it through frontpage modules enable.

Two doors share one monthly allowance, labeled Email sends.

• Mailings (frontpage mail) is campaigns: saved drafts, reusable templates, a series of those templates, one-off sends, the send ledger, enrolments, and the suppression list. Growth, Scale, and Enterprise. Each message carries a postal line and an unsubscribe link.
• Triggered mail is the message a visitor just caused: a form confirmation, the staff note to notifyEmail, and a store receipt. Starter and above, while the month still has room. These go out immediately. They do not use the campaign footer.

frontpage mail settings set --postal "100 Main St, Springfield" --reply-to you@example.com
frontpage mail template create --file welcome.json --name Welcome
frontpage mail series create --name Welcome
frontpage mail series steps set <series-id> --step template=<template-id>,delay=0
frontpage mail series activate <series-id>
frontpage mail send series <series-id> --to ada@example.com --var first_name=Ada
frontpage modules forms set --instance start --notify-email sales@example.com --confirm-template <template-id>

frontpage mail is in current frontpage-host. If the binary says Unknown command: mail, upgrade with npm i -g frontpage-host@latest. --confirm-template on forms requires frontpage-host 0.1.23 or later. Older installs report that flag as unknown.

Why these are not the same command

Agents keep routing every email through one verb. They are siblings.

• A form confirmation is not a campaign. Do not enrol the submitter from mail send to “confirm” a form.
• Choosing a template on a form does not start a series. A series is not attached to a form or an order.
• Login codes, team invites, and Frontpage billing mail are not this feature and do not count.

Who can send

On a plan that includes frontpage mail, the key still has to be a member of --site. Viewer can list and get. Editor and admin can create, send, and delete. A viewer mutate is HTTP 403. A key that is not a member gets HTTP 404 Site not found. Same fence as People and Store. See Isolation & keys.

• --site is a subdomain slug (acme). Not a custom domain, not acme.frontpage.host, not a site UUID. Resolution order is the same as People: this command’s --site, then .frontpage/state.json from frontpage use, then exit 2.
• There is not a second campaign allowance. Campaign recipients and series steps draw from Email sends.
• At the month’s allowance the form still saves the submission. The confirmation and the staff email are skipped until the month resets. A campaign send returns 429 This month's email sends are used. There is no grace past 100%.
• Downgrade keeps the template id on the form and the saved campaigns. Sends stop. Nothing is deleted. Upgrade turns them back on.

Settings

A campaign or series will not leave until the site has a postal line. That line is the physical address in the footer. Reply-to is where a human reply goes. From-name is the display name. Timezone is an IANA zone and defaults to UTC.

frontpage mail settings
frontpage mail settings get
frontpage mail settings set --postal "100 Main St, Springfield" --reply-to you@example.com --from-name "Acme" --timezone America/Chicago

Only flags you pass are patched. Human output of settings get is timezone postal reply-to on one line.

Two more fields exist on the API and are not CLI flags. sendWindowStart and sendWindowEnd are minutes from midnight in that timezone, 0 through 1440. Defaults are 480 and 1200 (08:00–20:00). Later steps of a series wait until that window. hourlyCap is an integer from 1 to 1000, or null to use the default pace of 100 campaign sends an hour. That pace is not the monthly Email sends allowance. Form confirmations and order receipts do not wait for the window and do not use this pace.

Drafts and templates

A draft (mail email) is one unsent email. A template (mail template) is reusable: series steps point at templates, and a form or a store receipt can point at one template. The verbs are the same.

frontpage mail email list
frontpage mail email get <id>
frontpage mail email create --file draft.json --name Hours
frontpage mail email set <id> --subject "We are open"
frontpage mail email preview <id>
frontpage mail email rm <id>

frontpage mail template list --q welcome --limit 50
frontpage mail template get <id>
frontpage mail template create --file welcome.json
frontpage mail template set <id> --file welcome.json
frontpage mail template preview <id>
frontpage mail template rm <id>

• email list is unsent drafts only. A sent one-off leaves that list. Read it with mail sends list.
• List flags: --q (name or subject), --limit (1–200, default 50), --cursor (opaque, from the previous page’s nextCursor). Do not invent a cursor.
• Create requires --file, a JSON object. --name, --subject, and --preheader override the file. The file must still include blocks, and on create it must include name, subject, and preview text unless those flags supply them.
• set patches only the keys you pass. --file is optional on set.
• The id is a UUID from list or create. Positional, or --id. A non-UUID is rejected locally. A UUID from another site is 404 Document not found.
• Caps: 50 unsent drafts per site, 50 live templates per site. Past that, create fails with the cap message.
• Name max 120. Subject max 200. Preview text (preheader) max 200 and required. Empty name, subject, or preview text is 400.
• rm is a soft delete. A template still used by a series is 409 This template is used by a series. A template still chosen on a form is 409 and names those forms. Remove it from the form first. A sent draft cannot be edited: A sent email cannot be edited. Duplicate it into a new draft.
• preview compiles the saved document and prints the subject. It does not send and does not count.

The JSON file

Blocks are structured. Owner HTML is stripped. A token looks like {{first_name}}. Declare every token you wrote, except the two built-ins first_name and unsubscribe_url. A token that is not declared is rejected on save: Unknown template variable: ….

{
  "name": "Welcome",
  "subject": "Hello {{first_name}}",
  "preheader": "You are on the list",
  "variables": ["organization_name"],
  "blocks": [
    { "type": "heading", "level": 1, "text": "Welcome" },
    { "type": "paragraph", "text": "Thanks from {{organization_name}}. See [the site](https://example.com)." },
    { "type": "button", "label": "Visit", "href": "https://example.com" },
    { "type": "image", "src": "https://example.com/logo.png", "alt": "Logo" },
    { "type": "divider" },
    { "type": "list", "style": "bullet", "items": ["One", "Two"] }
  ]
}

Variable names are lowercase, start with a letter, and then letters, digits, _, or -, up to 64 characters. Organization Name is rejected: Variable names must be kebab or snake case. A block of text over 50,000 characters is rejected. An empty blocks array is Add at least one content block.

What a token fills

The same template document fills differently depending on which door sends it.

frontpage modules forms get --instance start
frontpage modules forms set --instance start --notify-email sales@example.com --confirm-template <template-id>
frontpage modules forms set --instance start --confirm yes
frontpage modules forms set --instance start --confirm-template=

<form data-fp-form="start">
  <input name="organization_name" />
  <input name="fundraiser_name" />
  <input type="email" name="email" />
</form>

frontpage modules signups set --notify-email hello@example.com --confirm no
frontpage modules booking set --notify-email book@example.com --hours "Mon–Fri 9–5"

frontpage mail series list
frontpage mail series create --name Welcome
frontpage mail series get <id>
frontpage mail series set <id> --name "Welcome sequence"
frontpage mail series set <id> --status paused
frontpage mail series activate <id>
frontpage mail series pause <id>
frontpage mail series steps set <id> --step template=<id>,delay=0 --step template=<id>,delay=2d
frontpage mail series steps set <id> --file steps.json
frontpage mail series rm <id>

{
  "steps": [
    { "templateId": "11111111-1111-1111-1111-111111111111", "delayMinutes": 0 },
    { "templateId": "22222222-2222-2222-2222-222222222222", "delay": "2d" }
  ]
}

frontpage mail send --file email.json --to ada@example.com --to grace@example.com --wait
frontpage mail send email <draft-id> --to ada@example.com --name "Ada Lovelace" --var first_name=Ada
frontpage mail send template <template-id> --to ada@example.com --test
frontpage mail send series <series-id> --to ada@example.com,grace@example.com

frontpage mail sends list
frontpage mail sends list --batch <batch-id> --limit 50
frontpage mail sends get <send-id>

frontpage mail enrolments list
frontpage mail enrolments list --series <series-id>
frontpage mail enrolments cancel <enrolment-id>

frontpage mail suppress list
frontpage mail suppress add --email bounce@example.com
frontpage mail suppress rm --email bounce@example.com

frontpage mail settings set --postal "100 Main St, Springfield" --reply-to owner@example.com --timezone America/Chicago

frontpage mail template create --file welcome.json --name Welcome
# prints the template UUID

frontpage mail series create --name Welcome
frontpage mail series steps set <series-id> --step template=<template-id>,delay=0 --step template=<template-id>,delay=2d
frontpage mail series activate <series-id>
frontpage mail send series <series-id> --to ada@example.com --var first_name=Ada --wait

frontpage mail enrolments list --series <series-id>
frontpage mail sends list
frontpage mail suppress add --email bounce@example.com

frontpage modules forms set --instance start --notify-email sales@example.com --confirm-template <template-id>