People CRM

Get started

Use the current frontpage-host CLI. Sign in, then choose a site using --site on each command or frontpage use YOUR_SITE. A site is its subdomain slug, such as acme, not a full URL or UUID.

npm install -g frontpage-host@latest
frontpage login
frontpage people overview --site YOUR_SITE --json
frontpage people sources --site YOUR_SITE --json
frontpage people list --site YOUR_SITE --limit 50 --json

Replace YOUR_SITE and all uppercase ID placeholders before running an example. Copy IDs from real results: groups, stages, people, rules, templates, and series use UUIDs. Forms use a stable form slug; products use their item ID. Do not invent IDs.

--json returns structured output. Complex data accepts --file payload.json or --data 'JSON'. Use frontpage help people and frontpage help mail for command flags.

Contacts, notes, and history

Each contact needs a valid email or phone. A name is optional. If you supply both identifiers, both must be valid. Matching email or phone updates the existing contact; conflicting identities fail instead of merging two people.

frontpage people add --email alex@example.com --name "Alex Rivera" --site YOUR_SITE --json
frontpage people get PERSON_ID --site YOUR_SITE --json
frontpage people set PERSON_ID --name "Alex Rivera" --phone +12025550166 --site YOUR_SITE --json
frontpage people set PERSON_ID --address-name "Alex Rivera" --line1 "12 Main St" --line2 "Suite 4" --city Austin --region TX --postal 78701 --country US --site YOUR_SITE --json
frontpage people note PERSON_ID --body "Asked for a quote. Call on Friday." --site YOUR_SITE --json
frontpage people follow-up PERSON_ID --at 2026-11-06T15:00:00Z --site YOUR_SITE --json
frontpage people list --follow-up due --site YOUR_SITE --json
frontpage people hide PERSON_ID --site YOUR_SITE --json
frontpage people unhide PERSON_ID --site YOUR_SITE --json

• Details: name, email, phone, mailing address, original source, first seen, and last seen. Address fields include recipient name, line 1, line 2, city, region, postal code, and country.
• Notes: people note PERSON_ID --body "…" adds a manual note. people rm-note PERSON_ID --event NOTE_EVENT_ID removes an owner’s manual note. Source submissions and payments are not removable notes.
• Follow-up: set an ISO date with --at; clear it with people follow-up PERSON_ID --clear. The person page highlights overdue dates.
• Activity: people get returns the recent 50 events. Use person.activity for paged CRM and email history. The person page shows populated categories with loaded counts. Group and stage pages do not show a separate activity feed.
• Hide and restore: hide is recoverable. It retains identity, history, and membership. It excludes the person from campaign audiences and automated emails. Later source ingest may restore them.

Find and export people

People list and detail reads include eligible and reasonCode. The UI shows Can email or Can't email from the same policy used by the email picker. Codes are allowed, no_active_email, delivery_restricted, unsubscribed, not_allowed, and permission_missing. Hidden or missing/invalid email addresses use no_active_email. These read fields do not grant consent or promise sender readiness, budget, or delivery. API, people list --json, people get --json, list_people, and get_person return the same fields. CSV includes groups and stages instead of global status and tags.

people list and people export accept search, group, stage, source, form, follow-up, hidden state, sort and recency. List defaults to 50 contacts, supports up to 200 per page, and returns nextCursor. Pass that cursor to --cursor to continue. Export writes UTF-8 CSV; it is a contact export, not a complete activity archive.

Groups: organize people

In the workspace, open People CRM, then choose the People or Groups tab. Group details has Group details, Stages and Rules tabs. Use Email on Group details for joining emails. On a stage, Manage rules lets you create a rule, place an existing rule, or attach an email. Placement changes where a rule appears; its Start when event still controls execution. New attachments save paused.

A person can belong to several groups at once. Use a group for Leads, Customers, Newsletter, or another useful list. Rename a group freely: its ID stays the same.

Add people yourself or with rules

A manual group keeps membership until you, the agent, an import, or a rule changes it. These commands also manage the groups shown in the People filter.

frontpage people groups create --label Leads --color sky --mode manual --site YOUR_SITE --json
frontpage people groups list --site YOUR_SITE --json
frontpage people groups update --id GROUP_ID --label "New enquiries" --site YOUR_SITE --json
frontpage people membership add --person PERSON_ID --group GROUP_ID --site YOUR_SITE --json
frontpage people membership get --person PERSON_ID --site YOUR_SITE --json
frontpage people list --group GROUP_ID --site YOUR_SITE --json
frontpage people export --group GROUP_ID --out leads.csv --site YOUR_SITE
frontpage people groups archive --id GROUP_ID --site YOUR_SITE --json
frontpage people groups restore --id GROUP_ID --site YOUR_SITE --json

Before a reviewed groups.update, read groups.list and pass its saved emailVersion as expectedGroup through --data or --file. Email tasks use this full saved-configuration check. A changed name, color, mode, conditions or archive state returns 409 before writes; membership counts do not change the version. Read and review the latest settings before retrying. The check is optional for existing callers.

Independent edits can pass expectedFields through JSON with saved values for label, color, mode, conditions, or archivedAt. Only supplied fields are compared. Omitted update fields keep their current saved values. A stale comparison returns 409 without writing. Read and review saved values before submitting a revised edit.

Select people from a manual group

The group header offers Add people for manual groups and View matching people for conditional groups. Membership selection includes visible phone-only contacts and people without marketing permission. Current members show Already in this group and cannot be selected.

groups.people accepts groupId, optional q, source, sort (newest, oldest, name), page, selectedOnly, selected IDs and availability (all, available, member). Availability filters saved membership before counting and paging; it never filters by email permission. It returns 20 people per page, the full filtered total, actual page, phone/email details and member. It rejects conditional or archived groups and never records consent.

frontpage people workspace groups.people --group GROUP_ID --data '{"page":1,"q":"Alex"}' --site YOUR_SITE --json
frontpage people workspace membership.addMany --file selected-people.json --site YOUR_SITE --json

selected-people.json contains {"groupId":"GROUP_ID","personIds":["PERSON_ID"]}. membership.addMany accepts 1 to 20 IDs per request. The UI selects up to 100 and submits batches of 20. Results include added, alreadyMember, skipped, failed and per-person results with personId, status and an optional message. Keep failed or unconfirmed IDs for retry. Current members keep their stages and do not receive duplicate join events. Hidden people are skipped. A group changed to conditional or archived cannot receive additions through this operation. Successful additions save immediately and use normal active entry rules. They do not grant email permission or change other groups.

groups.count accepts a saved group id or explicit conditions. It checks all visible people in one consistent read and returns matched, checked, unknown, complete and sendsNothing:true. A known purchase count of zero does not match last-purchase date comparisons; it is not missing information or a purchase today. Use purchase count equal to zero for people who have never purchased. Actual unavailable facts remain unknown. A failed read is an error, never zero. The workspace shows this count under the condition editor. Saved group members open in the People tab with the group selected. The count describes the proposed conditions; the People list shows saved membership.

Create the group with a name and complete conditions if Match conditions is selected. Existing groups have no page-wide Save group button. Names save when editing finishes; colors save on selection. Edit How people join in its own modal and click Apply changes to save membership settings. X, Cancel, and Escape discard unapplied membership edits and close immediately without another prompt. The backdrop does not close the modal. Activate and Pause save immediately. Emails, stages, and rules save independently. Use a stable requestKey with groups.create or groups.update and retry the exact original key and payload after a lost response.

groups.preview accepts limit (1 to 200, default 200) and cursor, returning checked, unknown, matches and nextCursor. Match rows include phone and email. A batch may have no matches while more people remain. Counts describe people checked, not saved membership. With a saved group ID, pass expectedConditions to reject a condition or mode change between pages. Explicit conditions previews edits without saving them. Preview changes no membership and sends no email.

Keep a group matched to conditions

An automatic group uses saved contact facts. The worker checks contacts in rotating batches and updates membership as those facts or time change. Preview first. Save this as repeat-buyers.json:

{
  "label": "Repeat buyers",
  "color": "emerald",
  "mode": "conditions",
  "conditions": {
    "all": [
      {
        "field": "purchaseCount",
        "op": "gte",
        "value": 2
      },
      {
        "field": "lastPurchaseDays",
        "op": "lte",
        "value": 90
      }
    ]
  }
}

frontpage people groups count --file repeat-buyers.json --site YOUR_SITE --json
frontpage people groups create --file repeat-buyers.json --site YOUR_SITE --json
frontpage people membership override --person PERSON_ID --group GROUP_ID --override include --site YOUR_SITE --json
frontpage people membership override --person PERSON_ID --group GROUP_ID --override exclude --site YOUR_SITE --json
frontpage people membership override --person PERSON_ID --group GROUP_ID --override auto --site YOUR_SITE --json
frontpage people membership hold --person PERSON_ID --group GROUP_ID --hold false --site YOUR_SITE --json

include keeps one person in an automatic group; exclude keeps them out. auto clears the exception and applies that group’s conditions immediately when the needed facts are available. It can add or remove membership and run the group’s normal rules. It does not change other groups or email permission. An earlier saved pause still prevents automatic changes.

Earlier pauses. New --hold true requests fail unless the person already has that pause; an existing pause remains unchanged. Use --hold false to resume a saved pause. This keeps membership, stage and exception, restarts the time-rule clock, and skips earlier pending work for this person/group. It fails with HTTP 409 while a group rule is running; try again after it finishes. Archived groups must be restored first. No saved pause is cleared automatically. Failed runs remain available for an explicit review and retry; resuming does not retry them.

Archive groups instead of deleting their history. Assignments stay saved; related rules pause. Restoring a group does not reactivate those rules. Review and activate them explicitly.

Stages: track progress within a group

Stages are optional. A person can have one current stage per group, or no stage. A simple funnel might use New → Working → Customer. Save the group before adding stages or their rules.

frontpage people stages create --group GROUP_ID --label New --color sky --position 0 --site YOUR_SITE --json
frontpage people stages create --group GROUP_ID --label Working --color yellow --position 1 --site YOUR_SITE --json
frontpage people stages create --group GROUP_ID --label Customer --color emerald --position 2 --terminal true --site YOUR_SITE --json
frontpage people membership stage --person PERSON_ID --group GROUP_ID --stage STAGE_ID --site YOUR_SITE --json
frontpage people membership advance --person PERSON_ID --group GROUP_ID --site YOUR_SITE --json
frontpage people stages reorder --data '{"groupId":"GROUP_ID","stageIds":["NEW_ID","WORKING_ID","CUSTOMER_ID"]}' --site YOUR_SITE --json
frontpage people membership stage --data '{"personId":"PERSON_ID","groupId":"GROUP_ID","stageId":null}' --site YOUR_SITE --json
frontpage people stages archive --id STAGE_ID --group GROUP_ID --site YOUR_SITE --json
frontpage people stages restore --id STAGE_ID --group GROUP_ID --site YOUR_SITE --json

• Joining a group starts at its first stage when no previous stage exists. Rejoining keeps the prior stage; reset:true on add/move starts again.
• membership.advance follows ordered nonterminal stages. It stops when the current stage is final. Choose a final stage explicitly with membership.stage or a rule’s set_stage action.
• stageId:null clears the stage while keeping group membership.
• stages.reorder requires every active stage once. A duplicate, incomplete, or stale order fails without partially changing positions.
• Archiving a stage keeps its assignments and history and pauses related rules. Restoring it leaves those rules paused.

Rules: When / If / Then

Rules live beside their group or stage. Each has a start event, optional checks, and ordered actions. The editor saves new rules paused. Activate only after reviewing the result; activation applies to future events, not past submissions.

Example: follow up on an enquiry

Use a form slug from people sources. Save this as enquiry-rule.json:

{
  "name": "Follow up on contact enquiries",
  "trigger": {
    "event": "form.submitted",
    "formSlug": "contact",
    "owner": {
      "groupId": "GROUP_ID"
    }
  },
  "conditions": {
    "field": "email",
    "op": "present"
  },
  "actions": [
    {
      "type": "add_group",
      "groupId": "GROUP_ID"
    },
    {
      "type": "set_follow_up",
      "minutes": 1440
    }
  ],
  "enabled": false
}

frontpage people rules validate --file enquiry-rule.json --site YOUR_SITE --json
frontpage people rules preview --file enquiry-rule.json --person PERSON_ID --site YOUR_SITE --json
frontpage people rules create --file enquiry-rule.json --site YOUR_SITE --json
frontpage people rules enable --id RULE_ID --site YOUR_SITE --json
frontpage people rules pause --id RULE_ID --site YOUR_SITE --json
frontpage people rules update --id RULE_ID --file enquiry-rule.json --site YOUR_SITE --json
frontpage people rules runs --rule RULE_ID --limit 50 --site YOUR_SITE --json
frontpage people rules retry --run RUN_ID --site YOUR_SITE --json
frontpage people rules archive --id RULE_ID --site YOUR_SITE --json

Organize rules under a group or stage

The stage table opens Manage rules without leaving the group. Create a new paused rule, place an existing rule here, or attach a saved email as a paused entry rule. Each workflow returns to the stage manager. The Rules tab lists group and stage rules together and filters by placement. It shows the real event and ordered actions.

rules.get, rules.list and overview return an opaque revision for each rule. Call rules.place with id, expectedRevision and owner (groupId and optional stageId) to change only its placement. owner:null restores placement inferred from the real trigger/action groups. This operation accepts no execution edits.

frontpage people rules get --id RULE_ID --site YOUR_SITE --json
frontpage people workspace rules.place --file placement.json --site YOUR_SITE --json

placement.json contains {"id":"RULE_ID","expectedRevision":"REVISION_FROM_READ","owner":{"groupId":"GROUP_ID","stageId":"STAGE_ID"}}.

Placement validates active same-site references and rejects stale revisions with HTTP 409. It preserves the real trigger, name, conditions, actions, status, execution version, activation time, errors, run receipts and scheduled work. Only trigger.owner and the edit timestamp change. Read again after a conflict or uncertain response before retrying. General rules.update accepts optional expectedRevision; existing callers can still omit it.

New UI rules and email attachments save paused. Activate them separately. Generic attachment calls still default to active when enabled is omitted, so integrations that need review must send enabled:false. The UI removes optional condition authoring but displays and preserves existing saved conditions; CLI and agent condition support remains available. Duration controls offer minutes, hours, days and weeks while keeping exact whole minutes, including saved non-round values.

trigger.owner only places the rule in the editor. It never limits who can start the event. A form rule can belong to a stage without requiring the form submission to contain a group ID. Use conditions to limit it to existing members. Use trigger.groupId and trigger.stageId for membership events themselves.

When: choose a real event

Forms are detected from the current site’s module instances. Product choices come from active store items. Renaming a display label keeps the saved slug/item ID, so the rule keeps working. Deleting or replacing that ID requires updating the rule; validation rejects a missing source.

If: add only useful checks

Leave conditions null to run for every matching event. Use {all:[…]} when every check must match, or {any:[…]} when one is enough. Sets accept 1–20 children, up to four levels and 100 total clauses.

Numeric values are whole numbers from 0 to 1,000,000,000. Amounts use integer cents: 2500 means 25.00. Purchase facts count recorded paid order/payment events and sum their amounts; they are not net revenue after refunds and do not convert currencies. Last activity means CRM activity, not anonymous page views. Unknown facts do not remove a person from an automatic group.

The simple editor offers Purchases, Activity, and Contact details. Existing advanced conditions—including nested sets and membership checks—remain available through the CLI and agent and stay intact during UI edits. Email permission is handled separately before each send.

Then: perform ordered actions

A rule accepts 1–10 actions. Add/remove/move actions target manual groups; automatic groups use conditions and owner exceptions. fromStageIds prevents a late event from resetting someone who has moved further through the funnel.

Example: move a paid lead to Customer

{
  "name": "Mark paid leads as customers",
  "trigger": {
    "event": "order.paid",
    "owner": {
      "groupId": "GROUP_ID",
      "stageId": "CUSTOMER_ID"
    }
  },
  "conditions": {
    "groupId": "GROUP_ID",
    "member": true
  },
  "actions": [
    {
      "type": "set_stage",
      "groupId": "GROUP_ID",
      "stageId": "CUSTOMER_ID",
      "fromStageIds": [
        "NEW_ID",
        "WORKING_ID"
      ]
    }
  ],
  "enabled": false
}

Example: send a follow-up after two days

{
  "name": "Follow up after two days",
  "trigger": {
    "event": "stage.elapsed",
    "groupId": "GROUP_ID",
    "stageId": "WORKING_ID",
    "delayMinutes": 2880,
    "owner": {
      "groupId": "GROUP_ID",
      "stageId": "WORKING_ID"
    }
  },
  "conditions": null,
  "actions": [
    {
      "type": "send_template",
      "templateId": "TEMPLATE_ID"
    }
  ],
  "enabled": false
}

Timed rules use minutes: 2880 is two days. They run through the worker, not a browser timer. Use rules runs to inspect outcomes and rules retry to retry eligible failed work. Rule edits create a new version; changed or paused rules cannot replay old runs.

Attach an email to a group or stage

Use one action, Attach an email, then choose a saved email template or a series with saved steps. Off records waiting enrollment at step 1; turning On starts those people. New series start On; existing Off series stay Off when edited. Group email rows, group/stage rule cards, the rule editor and the attachment picker warn when a linked series is Off and offer Open series. A rule can stay Active while its series is Off: people wait for that series, and other rule actions still work. Attaching a series or activating its rule does not turn the series On. An attachment creates a normal editable rule on group entry or stage entry. Campaigns are one-off emails and cannot be selected for automation.

Save a reusable template as welcome.json:

{
  "name": "Welcome to our business",
  "subject": "Thanks for getting in touch",
  "preheader": "Here is what happens next.",
  "blocks": [
    {
      "type": "paragraph",
      "text": "Thanks for getting in touch. Our team will contact you soon."
    }
  ]
}

frontpage mail template create --file welcome.json --site YOUR_SITE --json
frontpage people attachments create --group GROUP_ID --email-kind template --email-id TEMPLATE_ID --enabled false --site YOUR_SITE --json
frontpage mail series create --name "Getting started" --site YOUR_SITE --json
frontpage mail series steps set SERIES_ID --step template=TEMPLATE_ID,delay=0 --site YOUR_SITE --json
frontpage mail series activate SERIES_ID --site YOUR_SITE --json
frontpage people attachments create --group GROUP_ID --stage STAGE_ID --email-kind series --email-id SERIES_ID --enabled false --site YOUR_SITE --json
frontpage people rules enable --id ATTACHMENT_RULE_ID --site YOUR_SITE --json

Copy the attachment’s returned rule ID before enabling it. Pass --enabled false to review it first. Omitting enabled on the API keeps its existing enabled-by-default behavior; the editor explicitly saves paused attachments.

• A real group/stage reentry can send another template. Duplicate events and action retries do not send that same action twice.
• An existing email/series enrollment does not restart when the person reenters.
• Removing someone from a group does not automatically cancel a series. Add cancel_series to a group/stage rule when that is the intended behavior; it affects that group’s enrollment only.
• Pause or archive the attachment rule to detach it. This does not erase its history.

See the Email guide for content blocks, template variables, series step delays, sender settings, and email limits.

Marketing email permission

Permission belongs to the email address and site. Groups and stages never grant it. A person who opts out stays in their groups and stages. Campaign selection, rules, direct-address sends, series and delivery enforce saved withdrawals and restrictions.

Defaults and explicit choices

The add choice is allowed, unknown, or not_allowed. API and agent callers use the same emailPermission string field. CLI callers use --email-permission. Recording allowed asserts that you have permission; it does not obtain permission from the person.

# New owner-added contacts default to permission given. Repeated adds preserve decisions.
frontpage people add --email alex@example.com --site YOUR_SITE --json
# Choose unknown when you do not have a recorded agreement:
frontpage people add --email pat@example.com --email-permission unknown --site YOUR_SITE --json
# Record refusal without enabling marketing:
frontpage people add --email sam@example.com --email-permission not_allowed --site YOUR_SITE --json
frontpage people membership get --person PERSON_ID --site YOUR_SITE --json
# Explicitly stop or record a new owner decision on the person:
frontpage people person permission --person PERSON_ID --allowed false --site YOUR_SITE --json
frontpage people person permission --person PERSON_ID --allowed true --site YOUR_SITE --json

membership.get reports eligibility and the reason mail cannot send. A missing/invalid email, hidden person, missing permission, recorded refusal, subscriber unsubscribe or suppression can block marketing. An active subscriber agreement can establish permission even without a separate CRM flag. A requested test copy can go to its test recipient without a recorded grant or a new subscription. Saved withdrawals, hidden state and suppression still apply. Transactional confirmations keep their own existing sending flow.

An explicit address outside People is an owner-asserted recipient and does not create a CRM permission record. If that address matches a saved person, the normal CRM eligibility check applies. Known subscribers' unsubscribe and saved suppressions also apply when no CRM person matches. Once queued, a known person's ID stays attached so a later address change, hide or withdrawal prevents delivery. A test is not a way to send a customer campaign.

New CRM decisions store state, exact email, source, actor and recording time in attrs.emailPermissionRecord; the boolean attrs.emailPermission stays compatible with existing callers. Historical grants without that record remain supported. Permission events preserve the decision history. Do not add a permission condition to every rule; the sender already checks it.

Repair reviewed historical permission without running rules

Review each person's current address, agreement evidence, saved withdrawals and restrictions first. This operation only fills missing permission. It never adds a person, changes their groups/stages, clears a restriction, or replays automation.

Save repair.json with real values:

{
  "personId": "PERSON_ID",
  "allowed": true,
  "backfill": true,
  "expectedEmail": "alex@example.com",
  "evidence": "Owner confirmed this person's marketing-email agreement on 2026-10-12",
  "requestKey": "UNIQUE_REPAIR_UUID"
}

frontpage people person permission --file repair.json --site YOUR_SITE --json
frontpage people membership get --person PERSON_ID --site YOUR_SITE --json

Reuse the same key and evidence after a lost response. A repeat returns duplicate:true without changing the decision again. If the person withdrew permission afterward, a retry does not restore it. A changed address, hidden person, existing decision, active subscriber agreement, unsubscribe or suppression refuses a new backfill. A new explicit owner decision uses the normal allowed operation instead; it still cannot reverse a subscriber unsubscribe or suppression.

For a reviewed cohort, submit at most 25 people in each bounded batch. Each row needs its own stable request key:

{
  "allowed": true,
  "backfill": true,
  "evidence": "Owner confirmed marketing-email permission for this reviewed cohort",
  "people": [
    { "personId": "PERSON_ID", "expectedEmail": "alex@example.com", "requestKey": "UNIQUE_REPAIR_UUID" }
  ]
}

Run the same person permission --file reviewed-batch.json command. Read every row in results: domain conflicts include error and status, while successful rows include emailPermission and duplicate. The batch can partly succeed; receipts make a retry safe. Malformed batch input fails before any permission writes. Infrastructure errors can leave completed receipts, so retry the exact batch rather than inventing new keys. This capability works through the public API and manage_people too; it has no company-only endpoint.

Import a customer list from CSV

CSV imports accept up to 5 MB and 10,000 contact rows. Quoted commas, quoted newlines, UTF-8 BOM, and CRLF are supported. Larger lists need separate files; the UI does not render an unbounded list of failures.

The UI offers only Add people groups as import destinations and sends manualGroupsOnly:true. CLI and agent callers can pass the same option to import.start. The saved job retains it. If a destination changes to Match conditions before processing, affected rows report an error instead of gaining an include exception. Completed rows stay saved. Restore Add people mode and retry the saved job, or preview a new import without that group. Existing accepted jobs and deliberate advanced imports keep their policy when the option is omitted.

1. Upload and map columns

Full name,Email address,Phone,Permission
Alex Rivera,alex@example.com,,
"Pat, Jr.",pat@example.com,+12025550166,yes
Phone customer,,+12025550199,

Map exact header names in mapping.json. Row values yes/true record an owner assertion; no/false record refusal. Top-level emailPermission chooses allowed, unknown or not_allowed for new contacts with no row value; omission defaults to allowed for new imports. Accepted imports keep their saved policy on retries. Row values take priority, duplicate rows keep negative values, and list-wide choices preserve existing decisions. Imports cannot reverse refusals, unsubscribe or suppression. Use a new request key when the list choice changes.

{
  "mapping": {
    "name": "Full name",
    "email": "Email address",
    "phone": "Phone",
    "emailPermission": "Permission"
  },
  "groupIds": [
    "GROUP_ID"
  ]
}

2. Review matching and errors

Preview returns real new/existing counts, normalized rows, fields that can fill blank saved details, duplicates, and errors. A name is optional; email or phone is required. Existing nonblank contact details stay saved. A repeated identity collapses into one contact; conflicting email/phone matches fail instead of merging different people.

The editor groups failures by reason, shows five examples per page, and shows ten ready contacts per page. There is no error download. Fix rows in the editor or upload a corrected CSV. The API returns bounded results for the accepted file limit.

3. Start and follow the saved import

frontpage people import preview --csv customers.csv --file mapping.json --site YOUR_SITE --json
frontpage people import start --csv customers.csv --file mapping.json --request-key REQUEST_UUID --site YOUR_SITE --json
frontpage people import get --id IMPORT_ID --site YOUR_SITE --json
# After correcting a saved contact conflict, retry the same job:
frontpage people import retry --id IMPORT_ID --site YOUR_SITE --json

Choose a fresh request UUID for each new import. If a response is lost, repeat import.start with the same key and unchanged CSV/mapping/groups. It returns the existing job. Reusing a key for different contents returns a conflict.

The worker saves its cursor and each row’s outcome, so closing the editor does not stop the job. Use import.get to inspect completion and failed rows. Correcting the CSV requires a new preview and new import key. import.retry retries failed rows from the original saved file after you fix the underlying saved contact conflict. Completed rows keep their receipts. Imports do not send emails or grant permission through group membership.

Email all people, a group, a stage, or selected people

The People button names the selected audience, such as Email all people or Email Newsletter. It opens a one-off draft in Emails. Drafting and sending stay there. Use a template creates an independent campaign draft; editing it never changes the source template.

Save audience.json:

{
  "audience": {
    "groupIds": [
      "GROUP_ID"
    ]
  }
}

ID lists combine as a union; filters narrow the result. Filters support q, source, formSlug, followUp, and lastSeenDays. An empty audience object is invalid; all people uses {"filters":{}} explicitly.

update.json uses the same saved email content shape shown above, with your campaign’s subject and blocks. Create it as an email draft, not a template:

frontpage mail email create --file update.json --name "Customer update" --site YOUR_SITE --json
frontpage mail campaign preview --file audience.json --site YOUR_SITE --json
frontpage mail campaign audience --id DRAFT_ID --file audience.json --site YOUR_SITE --json
# This command sends the campaign. Inspect the preview and draft first.
frontpage mail campaign send --id DRAFT_ID --request-key REQUEST_UUID --site YOUR_SITE --json
frontpage mail campaign get --id DRAFT_ID --site YOUR_SITE --json

Preview reports matched, eligible, no-email, suppressed, and permission-missing counts and sends nothing. Sending freezes content and eligible recipients, deduplicates email addresses, and uses the existing paced email queue. Reuse the send request key after a lost response. Check campaign get for queued, sent, pending, failed, and skipped work; queued does not mean delivered.

CLI, API, and agent reference

The editor, public API, CLI, and site agent call the same application service. Every operation below is available without opening the UI.

frontpage people workspace stages.reorder --file order.json --site YOUR_SITE --json
frontpage people rules create --data '{"name":"New leads","trigger":{"event":"person.added"},"conditions":null,"actions":[{"type":"set_follow_up","minutes":1440}],"enabled":false}' --site YOUR_SITE --json

Public API

POST /api/v1/sites/YOUR_SITE/people/workspace
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"operation":"groups.create","label":"Leads","color":"sky","mode":"manual"}

The public workspace endpoint takes operation fields at the top level. The agent tool uses a payload object instead. Campaign operations use POST /api/v1/sites/YOUR_SITE/mail/campaign with operation set to preview, audience, send, or get. Existing contact endpoints remain available under /api/v1/sites/YOUR_SITE/people.

Site agent

Ask the agent to use get_people_docs, then manage_people. Its tool binds the current site and access rights; do not pass a site ID or slug. Example membership request:

{
  "operation": "membership.add",
  "payload": {
    "personId": "PERSON_ID",
    "groupId": "GROUP_ID"
  }
}

Example campaign preview:

{
  "area": "campaign",
  "operation": "preview",
  "payload": {
    "audience": {
      "stageIds": [
        "STAGE_ID"
      ]
    }
  }
}

The agent can create and edit saved templates and series with the existing Email tools, then attach their IDs. It can inspect runs, retry failures, update contacts, import lists, and manage group exceptions directly.

Workspace operation reference

Limits, timing, and recovery

• Worker timing: the existing People worker runs every five minutes and handles saved imports, account sync, condition groups, timed rules, and pending actions. Work starts on a later scheduled pass; a busy queue or retries can take longer than five minutes.
• Temporary failures: eligible rule actions retry with bounded backoff, up to eight attempts. Permanent errors stay visible until corrected. Completed actions retain their receipts.
• Safe activation: new UI rules and attachments start paused. Enabling applies to future events. Updating a rule changes its version and does not replay old events.
• Safe membership: cycle checks reject rules that would repeatedly add/remove or move people in a loop. Stage guards prevent late events from resetting later progress.
• Safe email: sending uses the existing monthly/hourly/site limits, platform cap, provider pacing, and kill switch. Permission and suppression are checked at delivery.
• Safe retries: reuse a request key only for the same import or send. Inspect the saved job/run before starting a replacement.
• Safe changes: rename labels while retaining IDs. Archive instead of deleting records. Review paused rules when restoring groups or stages.

frontpage people workspace person.lookup --site YOUR_SITE --data "{\"email\":\"alex@example.com\"}" --json

frontpage people workspace person.update --site YOUR_SITE --data "{\"personId\":\"PERSON_ID\",\"patch\":{\"phone\":\"+12025550100\"},\"expected\":{\"phone\":null},\"historical\":true}" --json

frontpage people workspace notes.add --site YOUR_SITE --data "{\"personId\":\"PERSON_ID\",\"body\":\"Verified billing context\",\"requestKey\":\"YOUR_STABLE_KEY\",\"historical\":true}" --json

frontpage people workspace template.campaign --site YOUR_SITE --data "{\"templateId\":\"TEMPLATE_ID\",\"requestKey\":\"YOUR_STABLE_KEY\",\"audience\":{\"personIds\":[\"PERSON_ID\"]}}" --json

frontpage people workspace series.preview --site YOUR_SITE --data "{\"seriesId\":\"SERIES_ID\",\"personIds\":[\"PERSON_ID\"]}" --json

{
  "requestKey": "a-stable-group-template-save",
  "document": {
    "kind": "template",
    "name": "Group welcome",
    "subject": "Welcome, {{first_name}}",
    "preheader": "Thanks for joining us.",
    "blocks": [{"type":"paragraph","text":"Welcome to our group."}],
    "variables": []
  },
  "attachment": {
    "groupId": "GROUP_ID_FROM_GROUPS_LIST",
    "expectedGroup": "EXACT_EMAIL_VERSION_FROM_GROUPS_LIST"
  }
}

frontpage people workspace series.preview --site YOUR_SITE --data '{"seriesId":"SERIES_ID","audience":{"groupIds":["GROUP_ID"],"filters":{"q":"Alex"}}}' --json
frontpage people workspace person.activity --site YOUR_SITE --data '{"personId":"PERSON_ID","limit":50}' --json