Flashpoint.AIFlashpoint.AIdocs

Email distribution

Send tracked survey invitations to your own contact list. Each recipient gets a unique tokenized link, and you can monitor delivery, clicks, and completions per person.

Creating an email list

An email list ties a set of recipients to a survey. Create one by providing emails inline or by referencing a saved custom panel.

From inline emails

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 Customer Feedback",
    "emails": [
      {"email": "anna@example.com", "name": "Anna Chen"},
      {"email": "bob@example.com", "name": "Bob Patel"},
      {"email": "carol@example.com", "segment": "enterprise"}
    ]
  }'

Response:

{
  "id": "el_a1b2c3d4-...",
  "survey_id": "srv_...",
  "name": "Q4 Customer Feedback",
  "total_count": 3,
  "sent_count": 0,
  "validation_status": "pending",
  "sending_status": "draft",
  "source_panel_id": null,
  "email_template": null,
  "created_at": "2026-05-26T14:00:00Z"
}

Each recipient object requires an email field. Additional metadata fields (name, segment, or any custom key) are stored and can be used for personalization or downstream analysis.

Duplicate emails within a list are silently skipped.

From a custom panel

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "panel_id": "pnl_f5e6d7c8-..."
  }'

The list inherits all contacts from the panel. Changes to the panel after creation do not affect the list.

Via the agent

"Create an email list for my NPS survey with anna@example.com and bob@example.com"

The agent calls create_email_list with the emails you provide. It will never invent or guess email addresses.

Custom panels

A custom panel is the simpler, API-first form of a reusable contact list: a flat set of addresses saved at the team level that can seed an email list on any survey. If you want per-person attributes, filters, consent tracking across sends and a console UI, use a first-party panel instead.

Create a panel

curl -X POST https://api.flashpoint.ai/api/v1/panels/custom \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Testers",
    "description": "Early access program members",
    "emails": [
      {"email": "tester1@example.com", "name": "Alice"},
      {"email": "tester2@example.com", "name": "Bob"}
    ],
    "tags": ["beta", "product"]
  }'

Response:

{
  "id": "pnl_f5e6d7c8-...",
  "name": "Beta Testers",
  "description": "Early access program members",
  "total_count": 2,
  "tags": ["beta", "product"],
  "created_at": "2026-05-26T14:00:00Z"
}

List panels

curl https://api.flashpoint.ai/api/v1/panels/custom?limit=50&offset=0 \
  -H "Authorization: Bearer $TOKEN"

Via the agent

"Create a custom panel called 'Q4 Enterprise Clients' with these emails: ..."

The agent calls create_custom_panel and returns the panel ID for future use.

Your own panels (first-party panels)

For a list you will reuse — customers, members, a student cohort, event attendees — build a first-party panel. It lives at the team level in Console → My Panels, keeps per-person attributes you can filter on, tracks consent (unsubscribes and bounces are remembered per person, not per list), and can be attached to as many surveys as you like.

StepWhere
Upload a spreadsheet (CSV / XLSX) and map the columnsConsole → My Panels → New panel
Add people by typing their addresses in chatAgent / MCP: "create a panel called Alumni 2026 with anna@…, bob@…"
Add more people laterConsole, or "add these people to my Alumni panel"
See who would actually be mailed"how many people on Alumni would get this survey?" (preview_panel_audience)
Send the survey"send my NPS survey to the Alumni panel" (send_survey_to_panel)
Remind people who have not finished"remind the Alumni panel" — the saved filter reaches the same people
Reach only people added since the last sendfilter __never_sent
Check how it is landing"how is the Alumni send doing?" (get_panel_send_report)

Rules the agent enforces for you:

  • It only ever adds addresses you typed. It will not invent, guess or use example addresses, and it will not read a spreadsheet from chat — upload those in the console.
  • Sending is irreversible, so it previews the audience and tells you the count before it sends, then asks you to confirm.
  • Anyone who has unsubscribed or bounced is excluded automatically and reported in the result.
  • The survey must be published first.

Each panel send creates a tracked email list under the survey, so everything below (template, tracking, resend, per-recipient status) applies to panel sends too.

Email template

Every send uses a template with three fields:

FieldDescriptionDefault
subjectEmail subject line (max 65 chars recommended)You're invited: {{SURVEY_NAME}}
bodyPlain-text body; must contain {{SURVEY_LINK}}Generic invitation text
cta_textCall-to-action button label (2-4 words)Take the Survey

Supported placeholders

PlaceholderSubstituted with
{{SURVEY_LINK}}Personalized survey URL with recipient token (required)
{{SURVEY_NAME}}Survey title
{{RECIPIENT_EMAIL}}Recipient's email address
{{SENDER_NAME}}From name (default: "Flashpoint Surveys")

AI-drafted templates

The agent can draft or rewrite invitation copy using the compose_email_template tool. It reads the survey's name, audience, objective, and estimated length to generate contextual copy.

"Draft a casual, friendly invitation email for this survey"

"Make the email shorter and mention the $10 incentive"

The tool returns a {subject, body, cta_text} object that you can pass directly to the send call. It does not save or send anything on its own.

Attaching a template at list creation

You can save a template on the email list at creation time:

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch Invite",
    "emails": [{"email": "user@example.com"}],
    "email_template": {
      "subject": "Quick 3-minute survey about your experience",
      "body": "Hi there,\n\nWe value your feedback. This takes about 3 minutes.\n\n{{SURVEY_LINK}}\n\nThanks!",
      "cta_text": "Share your feedback"
    }
  }'

The saved template is used as the default for sends and resends unless overridden.

Sending

Trigger delivery of an email list. The survey must be active (published) before sending. This action is irreversible.

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_survey_url": "https://flashpointopinions.com/{survey_id}"
  }'

Response:

{
  "id": "el_a1b2c3d4-...",
  "survey_id": "srv_...",
  "name": "Q4 Customer Feedback",
  "total_count": 3,
  "sent_count": 3,
  "validation_status": "validated",
  "sending_status": "sent",
  "source_panel_id": null,
  "email_template": null,
  "created_at": "2026-05-26T14:00:00Z"
}

What happens during a send

  1. ZeroBounce validation — every recipient is validated before anything is sent, on every path (API, console, panel sends, agent). Invalid, disposable, spam-trap and do-not-mail addresses are marked bounced; catch-all and unknown addresses are skipped as risky. If ZeroBounce itself is unavailable the unchecked addresses are skipped too, never sent unverified. Verdicts are remembered platform-wide, so an address validated in the last 30 days (90 for invalid, 7 for risky) is not checked again.
  2. Rate-limited delivery — emails are sent through SendGrid at 10/second to avoid spam-filter triggers.
  3. Token generation — each recipient gets a unique token appended to the survey URL so the response ties back to them.
  4. Bounce handling — hard bounces, drops and spam reports are recorded by the SendGrid event webhook, mark the recipient bounced or unsubscribed, and add the address to the team's suppression list so it is never mailed again.

Sending limits

Every team shares the same sending identity, so the platform protects its sender reputation with a weekly budget:

LimitDefaultScope
Invitations + reminders per week100Per team, across all surveys, resets Monday 00:00 UTC
Per conversation, per survey50Agent and MCP sends only
Delivery rate10 / secondPlatform-wide

A send that would exceed the weekly budget is refused before any email goes out with a 429 and code email_weekly_cap_exceeded. The list stays in pending, so you can send it once the budget resets or is raised. The error body carries used, attempted, remaining and resets_at:

{
  "error": {
    "code": "email_weekly_cap_exceeded",
    "message": "This team has reached its weekly email limit of 100 invitations (80 already sent this week, 40 more attempted, 20 remaining). The limit resets on Monday 26 Oct at 00:00 UTC. For larger distributions, please reach out to help@flashpoint.ai.",
    "details": { "cap": 100, "used": 80, "attempted": 40, "remaining": 20, "resets_at": "2026-10-26T00:00:00+00:00" }
  }
}

Need more? Email help@flashpoint.ai with your team and expected volume; the limit is raised per team.

Every invitation also carries a one-click unsubscribe header and an opt-out link. Recipients who unsubscribe, bounce or report spam are suppressed for the whole team, and the suppression is applied automatically when you create a list or send to a panel.

Overriding the template for one send

Pass email_template in the send body to override the saved template for this send only:

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_survey_url": "https://flashpointopinions.com/{survey_id}",
    "email_template": {
      "subject": "Last chance: share your feedback",
      "body": "Hi,\n\nThis is your final reminder.\n\n{{SURVEY_LINK}}\n\nThank you!",
      "cta_text": "Take the survey now"
    }
  }'

Via the agent

"Send the email list to my survey recipients"

The agent calls send_email_list. Because sending is destructive (emails go out immediately), the agent presents an approval card before executing.

Tracking

Per-recipient status

curl "https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/recipients?page=1&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "recipients": [
    {
      "id": "rec_...",
      "email": "anna@example.com",
      "status": "completed",
      "validation_status": "valid",
      "sent_at": "2026-05-26T14:05:00Z",
      "last_sent_at": "2026-05-26T14:05:00Z",
      "send_count": 1,
      "started_at": "2026-05-26T15:10:00Z",
      "completed_at": "2026-05-26T15:14:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 50
}

Filter by status with the status query parameter:

# Only recipients who haven't completed
curl "...?status=sent"

Recipient lifecycle

pending --> sent --> clicked --> completed
                 \-> bounced
StatusMeaning
pendingAdded to list, not yet sent
sentEmail delivered
clickedRecipient opened the survey link
completedSurvey response submitted
bouncedDelivery failed (hard or soft bounce)

Summary statistics

curl "https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/stats" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "total": 100,
  "pending": 5,
  "sent": 30,
  "started": 15,
  "completed": 45,
  "bounced": 5
}

Resending

Send reminders to recipients who have not completed the survey.

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/resend \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_survey_url": "https://flashpointopinions.com/{survey_id}",
    "filter": "non_complete"
  }'

Filter options

FilterRecipients included
non_completeEveryone who has not completed (pending + sent + started + bounced). Default.
pendingOnly recipients whose email was never sent
sentOnly recipients who received the email but have not started
specificOnly the recipient_ids you specify

Specific-recipient resend

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/resend \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_survey_url": "https://flashpointopinions.com/{survey_id}",
    "filter": "specific",
    "recipient_ids": ["rec_abc123", "rec_def456"]
  }'

Resends reuse existing tokens (same survey link per recipient) and skip ZeroBounce re-validation.

Via the agent

"Resend the invitation to everyone who hasn't completed yet"

Adding recipients

Append new contacts to an existing email list after the initial send.

curl -X POST https://api.flashpoint.ai/api/v1/surveys/{survey_id}/email-lists/{list_id}/recipients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {"email": "newuser@example.com", "name": "New User"}
    ]
  }'

Response:

{
  "list_id": "el_a1b2c3d4-...",
  "added": 1,
  "skipped_duplicates": 0,
  "total_count": 4
}

New recipients are automatically validated and sent using the same pipeline as the initial send. Emails that already exist on the list are silently skipped (case-insensitive match).

Platform email

The send_platform_email tool sends platform-generated files (survey exports, reports, CSV data) to stakeholders. This is not a survey invitation — it is for sharing deliverables.

Requirements

  • At least one attachment is required (an s3_key from a prior export_csv, export_docx, or export_pdf call).
  • Maximum 10 recipients (to + cc combined).
  • Maximum 5 attachments, 25 MB total.
  • Recipients are validated via ZeroBounce before sending.

Via the agent

"Email the CSV export of this survey to stakeholder@company.com"

The agent first runs the export, captures the S3 key, then calls send_platform_email with the attachment. An approval card is presented before sending.

Next steps