polls

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 42 Imported by: 0

Documentation

Overview

Package polls is the Poll block and surveys (design expansion, M21): a question in an email whose answers are plain links, the answer page that records the answer (never the click, so link scanners can't vote), the results in the campaign report, and hosted multi-question surveys built in Forms & pages.

A poll's settings live in the email's MJML, in the poll section's rc-poll attribute, so they are versioned with the content. When a test or a send needs the poll's links, Sync copies them into polls; each recipient's answer link carries a signed token (linktoken.Poll) naming the poll, the message and the contact.

Index

Constants

View Source
const (
	AnswererContact    = "contact"
	AnswererNonContact = "non_contact"
	AnswererTest       = "test"
)

Who answers through a link.

View Source
const (
	KindChoice = "choice"
	KindScale  = "scale"
	KindEmoji  = "emoji"
)

Poll kinds.

View Source
const (
	SaveNone  = "none"
	SaveTag   = "tag"
	SaveField = "field"
)

Where an answer is saved on the contact.

View Source
const (
	CloseDays   = "days"
	CloseDate   = "date"
	CloseManual = "manual"
)

When a poll closes.

View Source
const (
	MaxShortAnswer = 200
	MaxLongAnswer  = 2000
)

Longest text answers: a short answer, and a long one.

View Source
const (
	QuestionSingle = "single"
	QuestionMulti  = "multi"
	QuestionScale  = "scale"
	QuestionEmoji  = "emoji"
	QuestionShort  = "short"
	QuestionLong   = "long"
)

Survey question types.

View Source
const (
	SurveyDraft  = "draft"
	SurveyOpen   = "open"
	SurveyClosed = "closed"
)

Survey statuses.

View Source
const FixCloseDays = "poll_close_days"

FixCloseDays makes a poll close N days after sending (Send Readiness' "Close 7 days after sending").

View Source
const MaxComment = 500

MaxComment is the longest comment: "Anything to add?", up to 500 characters.

View Source
const MaxQuestions = 20

MaxQuestions is how many questions a survey takes, all on one page.

View Source
const TooFew = 30

TooFew is the fewest answers a breakdown row compares: fewer read "Too few to compare".

View Source
const TriggerPollAnswered = "poll_answered"

TriggerPollAnswered is the automation trigger "Answered a poll or survey".

Variables

View Source
var ErrBadLink = errors.New("polls: the link doesn't work")

ErrBadLink is a link that doesn't verify: cut short, changed, or for a poll that no longer exists. Nothing is recorded.

Functions

func AnswerText

func AnswerText(q SurveyQuestion, v any) string

AnswerText is a question's answer in words: "Daily", "Feature flags, Audit log exports", "9", or the text.

func Erasure

func Erasure() erasure.Source

Erasure keeps poll answers and survey responses counted, unlinked from the contact, and drops what the person wrote (design expansion X11; review 2026-11 DP-1).

func FaceWord

func FaceWord(faces, key int) string

FaceWord is the words of an emoji answer ("very unhappy").

func FixMJML

func FixMJML(src, action string, params map[string]string) (next, label, applied string, err error)

FixMJML applies a poll fix to an email's MJML.

func PreviewLinks(src string) map[string]string

PreviewLinks are a preview's poll and survey link variables: links that go nowhere, so nothing is recorded from the composer.

func Register

func Register(h huma.API, s *Service)

Register adds the poll and survey operations.

func Section

func Section(c PollConfig, faceURL func(faces, key int) string) string

Section writes a Poll block's MJML from its settings: the question, the answers as plain links (MJML buttons, or cells for a scale), the ends' words and the note. The composer writes the same structure; this one is for the API and the demo. faceURL gives an emoji face's image.

func SurveyVar

func SurveyVar(number int64) string

SurveyVar is the Liquid variable holding a recipient's link to a survey.

func VarName

func VarName(id string) string

VarName is the Liquid variable holding a recipient's answer link base: an answer's link is {{ rc_poll_<id> }}/<key>.

Types

type Answer

type Answer struct {
	Key   int    `json:"key"`
	Label string `json:"label"`
	Emoji string `json:"emoji,omitempty"`
	Tag   string `json:"tag,omitempty"`
}

Answer is one answer of a poll with its key: 1… for choices and faces, 0–10 for a scale.

type AnswerPage

type AnswerPage struct {
	PollID       uuid.UUID
	WorkspaceID  uuid.UUID
	Config       PollConfig
	Answers      []Answer
	CampaignName string
	// Who: a contact (Name is their first name), a non-contact (archive
	// links) or a test address.
	Answerer string
	Name     string
	Email    string
	// ContactID and MessageID are the link's (the page's own links, such as
	// Email preferences, are signed for the contact).
	ContactID uuid.UUID
	MessageID uuid.UUID
	// SentAt is when the campaign started sending.
	SentAt *time.Time
	// Picked is the answer of the link; Answer the recorded one (nil
	// before this person answered).
	Picked int
	Answer *int
	// Previous is the answer this visit replaced (nil when it didn't).
	Previous *int
	Comment  string
	// Saved is true when this request recorded the answer (or the same
	// answer was already recorded).
	Saved bool
	// Closed polls record nothing; ClosedAt is when they closed.
	Closed   bool
	ClosedAt *time.Time
	ClosesAt *time.Time
	// Refused is a non-contact on a poll that doesn't take their answers.
	Refused bool
	// Automated is a visit the classifier attributed to a machine.
	Automated bool
	// Results are the shares, when the poll shows them after answering.
	Results *PollShares
	// SurveyURL continues to a survey when the poll says so.
	SurveyURL string
}

AnswerPage is everything an answer page shows.

type Export

type Export struct {
	Filename string
	Body     []byte
}

Export is a CSV file to download.

type FieldSource

type FieldSource struct {
	Field string    `json:"field"`
	Kind  string    `json:"kind" enum:"poll,survey"`
	Name  string    `json:"name"`
	At    time.Time `json:"at"`
}

FieldSource says where a contact field's value came from.

type FieldSources

type FieldSources struct {
	Items []FieldSource `json:"items"`
}

FieldSources are the fields of a contact that a poll or a survey set.

type PollAnswerConfig

type PollAnswerConfig struct {
	Label string `json:"label"`
	// Emoji is shown before the label; Tag is added when Save is "tag".
	Emoji string `json:"emoji,omitempty"`
	Tag   string `json:"tag,omitempty"`
}

PollAnswerConfig is one answer of a Choice poll.

type PollAnswerCount

type PollAnswerCount struct {
	Key     int     `json:"key"`
	Label   string  `json:"label"`
	Emoji   string  `json:"emoji,omitempty"`
	Tag     string  `json:"tag,omitempty"`
	Count   int64   `json:"count"`
	Percent float64 `json:"percent"`
}

PollAnswerCount is one answer's count and share of the answers.

type PollAutomatedVisits

type PollAutomatedVisits struct {
	Total    int64 `json:"total"`
	Gateways int64 `json:"gateways"`
	Prefetch int64 `json:"prefetch"`
}

PollAutomatedVisits are the visits ignored as a machine's.

type PollBlock

type PollBlock struct {
	Config PollConfig
	// Path is the section's element path from mj-body.
	Path []int
}

PollBlock is a Poll block found in an email.

func Read

func Read(src string) []PollBlock

Read finds an email's Poll blocks (sections with rc-poll).

type PollBreakdownRow

type PollBreakdownRow struct {
	Key     string            `json:"key"`
	Label   string            `json:"label"`
	Answers int64             `json:"answers"`
	Percent float64           `json:"percent"`
	TooFew  bool              `json:"tooFew"`
	NPS     *int              `json:"nps,omitempty"`
	Counts  []PollAnswerCount `json:"counts"`
}

PollBreakdownRow is one row of a breakdown: a tier, a list or a language, with its answers and, when it has enough, its NPS or shares.

type PollBreakdowns

type PollBreakdowns struct {
	Tiers     []PollBreakdownRow `json:"tiers"`
	Lists     []PollBreakdownRow `json:"lists"`
	Languages []PollBreakdownRow `json:"languages"`
}

PollBreakdowns are the answers by engagement tier, list and language.

type PollCampaignPath

type PollCampaignPath struct {
	api.WorkspaceInput
	CampaignID string `path:"campaignId" format:"uuid" doc:"Campaign id"`
}

type PollClose

type PollClose struct {
	Mode string `json:"mode" enum:"days,date,manual"`
	Days int    `json:"days,omitempty"`
	// Date is "2026-10-28": the poll closes at the end of that day in the
	// workspace's time zone.
	Date string `json:"date,omitempty"`
}

PollClose says when the poll stops recording answers.

type PollComment

type PollComment struct {
	ID     string `json:"id"`
	Answer int    `json:"answer"`
	Label  string `json:"label"`
	// Group of a 0–10 answer: promoter, passive or detractor.
	Group   string    `json:"group,omitempty" enum:"promoter,passive,detractor"`
	Comment string    `json:"comment"`
	At      time.Time `json:"at"`
	// Contact is the contact's name (people with subscribers:view), empty
	// otherwise; NonContact marks answers from people who aren't contacts.
	Contact    string `json:"contact,omitempty"`
	ContactID  string `json:"contactId,omitempty"`
	NonContact bool   `json:"nonContact"`
}

PollComment is one comment with its answer.

type PollCommentCounts

type PollCommentCounts struct {
	All        int64 `json:"all"`
	Promoters  int64 `json:"promoters"`
	Passives   int64 `json:"passives"`
	Detractors int64 `json:"detractors"`
}

PollCommentCounts are the comments by group, for the filter.

type PollCommentList

type PollCommentList struct {
	Items  []PollComment     `json:"items"`
	Total  int64             `json:"total"`
	Counts PollCommentCounts `json:"counts"`
	Names  bool              `json:"names"`
}

PollCommentList is a page of comments, newest first.

type PollCommentsFilter

type PollCommentsFilter struct {
	Group  string
	Search string
	Offset int
	Limit  int
}

PollCommentsFilter narrows the comments.

type PollConfig

type PollConfig struct {
	ID       string             `json:"id"`
	Kind     string             `json:"kind" enum:"choice,scale,emoji"`
	Question string             `json:"question"`
	Answers  []PollAnswerConfig `json:"answers"`
	// Layout of Choice answers: stacked buttons or one row.
	Layout string    `json:"layout,omitempty" enum:"stacked,row"`
	Save   string    `json:"save" enum:"none,tag,field"`
	Field  string    `json:"field,omitempty"`
	Close  PollClose `json:"close"`
	// After answering: the thank-you message, or continue to a survey whose
	// first question the answer fills.
	After  string `json:"after" enum:"thanks,survey"`
	Thanks string `json:"thanks,omitempty"`
	Survey string `json:"survey,omitempty"`
	// NonContacts: count answers from people who aren't contacts apart, or
	// refuse them.
	NonContacts string `json:"nonContacts" enum:"count,refuse"`
	// Results shows the shares on the answer page after answering.
	Results bool `json:"results"`
	// NPS uses the Net Promoter Score wording on a 0–10 scale; Low and
	// High are its ends' words.
	NPS  bool   `json:"nps,omitempty"`
	Low  string `json:"low,omitempty"`
	High string `json:"high,omitempty"`
	// Faces of an emoji scale: three or five.
	Faces int `json:"faces,omitempty"`
}

PollConfig is a Poll block's settings, as its rc-poll attribute stores them.

func ParseConfig

func ParseConfig(raw string) (PollConfig, error)

ParseConfig reads an rc-poll attribute value.

func (PollConfig) AnswerList

func (c PollConfig) AnswerList() []Answer

AnswerList is the answers a poll takes.

func (PollConfig) Encode

func (c PollConfig) Encode() string

Encode writes the settings as the attribute value.

func (PollConfig) ProblemTexts

func (c PollConfig) ProblemTexts() []i18n.Text

ProblemTexts are the poll's problems kept as messages, for text stored for later readers (a Send Readiness run).

func (PollConfig) Problems

func (c PollConfig) Problems() []string

Problems are what keeps a poll from working, in English: a missing question, fewer than two or more than five answers, a tag or field missing where answers are saved.

func (PollConfig) ProblemsIn

func (c PollConfig) ProblemsIn(l i18n.Lang) []string

ProblemsIn are the poll's problems in a reader's language.

type PollContactPath

type PollContactPath struct {
	api.WorkspaceInput
	ContactID string `path:"contactId" format:"uuid" doc:"Contact id"`
}

type PollNPS

type PollNPS struct {
	Score            int     `json:"score"`
	Promoters        int64   `json:"promoters"`
	Passives         int64   `json:"passives"`
	Detractors       int64   `json:"detractors"`
	PromoterPercent  float64 `json:"promoterPercent"`
	PassivePercent   float64 `json:"passivePercent"`
	DetractorPercent float64 `json:"detractorPercent"`
}

PollNPS is a 0–10 poll's Net Promoter Score: promoters (9–10) minus detractors (0–6), as percentages of the answers.

type PollOption

type PollOption struct {
	Key   int    `json:"key"`
	Label string `json:"label"`
}

PollOption is one answer a trigger can filter on.

type PollOverTime

type PollOverTime struct {
	Since *time.Time `json:"since,omitempty"`
	// Cumulative has one point per hour: answers by the end of hour i.
	Cumulative []int64 `json:"cumulative"`
	// FirstSixPercent is the share that came in the first 6 hours; After
	// the answers after 72 hours.
	FirstSixPercent float64 `json:"firstSixPercent"`
	After           int64   `json:"after"`
}

PollOverTime is the cumulative answers by hour over the first 72 hours.

type PollPath

type PollPath struct {
	api.WorkspaceInput
	PollID string `path:"pollId" format:"uuid" doc:"Poll id"`
}

type PollResults

type PollResults struct {
	ID         string `json:"id"`
	BlockID    string `json:"blockId"`
	CampaignID string `json:"campaignId,omitempty"`
	Campaign   string `json:"campaign"`
	Kind       string `json:"kind" enum:"choice,scale,emoji"`
	Question   string `json:"question"`
	NPSWording bool   `json:"npsWording"`
	Low        string `json:"low,omitempty"`
	High       string `json:"high,omitempty"`
	Save       string `json:"save" enum:"none,tag,field"`
	Field      string `json:"field,omitempty"`
	// Status: open (closes at ClosesAt, or by hand) or closed (by a person,
	// or as scheduled).
	Status            string     `json:"status" enum:"open,closed"`
	ClosesAt          *time.Time `json:"closesAt,omitempty"`
	ClosedAt          *time.Time `json:"closedAt,omitempty"`
	ClosedBy          string     `json:"closedBy,omitempty"`
	ClosedAsScheduled bool       `json:"closedAsScheduled"`
	ReopenedAt        *time.Time `json:"reopenedAt,omitempty"`
	StartedAt         *time.Time `json:"startedAt,omitempty"`
	// Live is a poll still collecting its first 72 hours of answers.
	Live bool `json:"live"`
	// Answers are contacts' answers; Percent their share of Delivered.
	Answers     int64               `json:"answers"`
	Delivered   int64               `json:"delivered"`
	Percent     float64             `json:"percent"`
	NonContacts int64               `json:"nonContacts"`
	Tests       int64               `json:"tests"`
	Changed     int64               `json:"changed"`
	Comments    int64               `json:"comments"`
	Automated   PollAutomatedVisits `json:"automated"`
	Counts      []PollAnswerCount   `json:"counts"`
	NPS         *PollNPS            `json:"nps,omitempty"`
	Breakdown   PollBreakdowns      `json:"breakdown"`
	OverTime    PollOverTime        `json:"overTime"`
	// AnswerPage is where its answer links go (the publisher's domain),
	// with "…" for the signed part; Config is the Poll block's settings
	// (rc-poll), for a preview of the answer page.
	AnswerPage string `json:"answerPage"`
	Config     string `json:"config"`
	// Names is true when comments carry the contacts' names
	// (subscribers:view).
	Names bool `json:"names"`
	// CanClose (campaigns:edit) and CanExportAnswers (subscribers:export)
	// are the viewer's; the helpers are members to ask when not.
	CanClose         bool     `json:"canClose"`
	CloseHelpers     []string `json:"closeHelpers"`
	CanExportAnswers bool     `json:"canExportAnswers"`
	ExportHelpers    []string `json:"exportHelpers"`
}

PollResults is a poll's section of the campaign report.

type PollResultsList

type PollResultsList struct {
	Items []PollResults `json:"items"`
}

PollResultsList are a campaign's polls with their results.

type PollShare

type PollShare struct {
	Key     int
	Label   string
	Count   int64
	Percent int
}

PollShare is one answer's share.

type PollShares

type PollShares struct {
	Total int64
	Rows  []PollShare
}

PollShares are a poll's results as the answer page shows them.

type PollSource

type PollSource struct {
	// Ref is "poll:<id>" or "survey:<id>", as the trigger stores it.
	Ref      string       `json:"ref"`
	Kind     string       `json:"kind" enum:"poll,survey"`
	Name     string       `json:"name"`
	Campaign string       `json:"campaign,omitempty"`
	PollKind string       `json:"pollKind,omitempty" enum:"choice,scale,emoji"`
	Status   string       `json:"status"`
	ClosesAt *time.Time   `json:"closesAt,omitempty"`
	Answers  []PollOption `json:"answers"`
}

PollSource is a poll or a survey the automation trigger "Answered a poll or survey" can start from.

type PollSourceList

type PollSourceList struct {
	Items []PollSource `json:"items"`
}

PollSourceList is the workspace's polls and surveys.

type PollTestAnswer

type PollTestAnswer struct {
	PollID  string    `json:"pollId"`
	BlockID string    `json:"blockId"`
	Email   string    `json:"email"`
	Answer  int       `json:"answer"`
	At      time.Time `json:"at"`
}

PollTestAnswer is one test address's answer to a campaign's poll.

type PollTestAnswers

type PollTestAnswers struct {
	Items []PollTestAnswer `json:"items"`
}

PollTestAnswers are the test answers of a campaign's polls, never counted.

type PollTestAnswersCleared

type PollTestAnswersCleared struct {
	Deleted int64 `json:"deleted"`
}

PollTestAnswersCleared says how many test answers were deleted.

type ReadinessFacts

type ReadinessFacts struct {
	Ran     bool
	Polls   []ReadinessPoll
	Surveys []ReadinessSurvey
	// Domain is the custom domain set for the public pages; DomainStatus
	// its check ("verified", "pending"…) and DomainDetail what the check
	// found. Instance is the address links use until it is verified.
	Domain       string
	DomainStatus string
	DomainDetail string
	Instance     string
	// TestAnswers counts the campaign's test answers (never counted).
	TestAnswers int
}

ReadinessFacts are an email's polls and surveys and where their links go.

type ReadinessPoll

type ReadinessPoll struct {
	ID       string
	Question string
	Path     []int
	Problems []string
	// ProblemTexts are the Problems kept as messages, for a run that keeps
	// its text for later readers.
	ProblemTexts []i18n.Text
	// Close says when it closes: Mode date with ClosesAt (the end of that
	// day), days with Days after sending, or manual.
	Close    PollClose
	ClosesAt *time.Time
}

ReadinessPoll is a poll of an email as Send Readiness checks it.

type ReadinessSurvey

type ReadinessSurvey struct {
	ID       string
	Name     string
	Status   string
	ClosesAt *time.Time
}

ReadinessSurvey is a survey an email links to.

type RecipientLink struct {
	Var string
	URL func(messageID, contactID uuid.UUID) string
}

RecipientLink is a per-recipient link variable of an email.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Links *linktoken.Signer
	URLs  publicurl.Builder
	// Forms gives the workspace's public page links (its verified custom
	// domain, else the instance's address).
	Forms *forms.Service
	Log   *slog.Logger
	Now   func() time.Time
}

Service runs polls and surveys.

func (s *Service) BrowserLinks(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) map[string]string

BrowserLinks are the link variables of an email shown on the web archive or "View in browser": its links carry no contact's token, so answers from there count as non-contacts' (or are refused, as each poll says). Polls are created when a test or the send needs them; until then the answer links go nowhere.

func (*Service) CampaignPolls

func (s *Service) CampaignPolls(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID) (PollResultsList, error)

CampaignPolls are the results of a campaign's polls, in the email's order.

func (*Service) CampaignReadiness

func (s *Service) CampaignReadiness(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, src string) ReadinessFacts

CampaignReadiness reads the facts of a campaign's content.

func (*Service) ClearTestAnswers

func (s *Service) ClearTestAnswers(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (int64, error)

ClearTestAnswers deletes a campaign's test answers (audited: answers deleted).

func (*Service) Comment

func (s *Service) Comment(ctx context.Context, wsID uuid.UUID, token, text string) (*AnswerPage, error)

Comment saves "Anything to add?" with a recorded answer.

func (*Service) Comments

Comments are a poll's comments, newest first, with names for people with subscribers:view.

func (*Service) ContactActivity

func (s *Service) ContactActivity(ctx context.Context, ws *store.Workspace, contactID uuid.UUID, before *time.Time, beforeID string, limit int) ([]audience.ContactActivityItem, int64, error)

ContactActivity is audience.ActivitySource: the answers before the cursor, newest first, and how many there are.

func (*Service) ContactFieldSources

func (s *Service) ContactFieldSources(ctx context.Context, ws *store.Workspace, contactID uuid.UUID) (FieldSources, error)

ContactFieldSources finds the fields a contact's answers set: the latest answer that saved to a field names it.

func (*Service) CreateSurvey

func (s *Service) CreateSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, in SurveyCreate) (Survey, error)

CreateSurvey makes a draft survey with no questions yet.

func (*Service) DeleteSurvey

func (s *Service) DeleteSurvey(ctx context.Context, ws *store.Workspace, id uuid.UUID) error

DeleteSurvey removes a survey; its page stops answering.

func (*Service) ExportPollAnswers

func (s *Service) ExportPollAnswers(ctx context.Context, ws *store.Workspace, pollID uuid.UUID) (Export, error)

ExportPollAnswers writes every answer with its contact (subscribers:export, audited).

func (*Service) ExportPollResults

func (s *Service) ExportPollResults(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID) (Export, error)

ExportPollResults writes a poll's results as CSV: aggregate numbers only, audited like the other report exports.

func (*Service) ExportSurveyAnswers

func (s *Service) ExportSurveyAnswers(ctx context.Context, ws *store.Workspace, id uuid.UUID) (Export, error)

ExportSurveyAnswers writes every response with its contact (subscribers:export, audited).

func (*Service) ExportSurveyResults

func (s *Service) ExportSurveyResults(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (Export, error)

ExportSurveyResults writes a survey's results as CSV, aggregate only.

func (*Service) GetSurvey

func (s *Service) GetSurvey(ctx context.Context, ws *store.Workspace, id uuid.UUID) (Survey, error)

GetSurvey returns one survey.

func (*Service) Page

func (s *Service) Page(ctx context.Context, wsID uuid.UUID, token string, picked int, v Visit) (*AnswerPage, error)

Page shows an answer page without recording anything: what the link picked, and the answer already recorded. A machine's visit is counted as an automated visit.

func (*Service) PollResultsOf

func (s *Service) PollResultsOf(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID) (PollResults, error)

PollResultsOf is one poll's results.

func (*Service) PublishSurvey

func (s *Service) PublishSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (Survey, error)

PublishSurvey opens a survey's page. Every question must be complete.

func (*Service) Record

func (s *Service) Record(ctx context.Context, wsID uuid.UUID, token string, answer int, v Visit) (*AnswerPage, error)

Record saves an answer from the page (its script's POST once the page was visible for a moment, or the Confirm button without JavaScript). The latest answer counts; a changed one replaces it, with the history kept.

func (*Service) Responses

func (s *Service) Responses(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, offset, limit int) (SurveyResponseList, error)

Responses lists a survey's completed responses.

func (s *Service) SendLinks(ctx context.Context, wsID, campaignID uuid.UUID) ([]RecipientLink, error)

SendLinks syncs a campaign's polls as its send starts and returns the link variables each recipient gets: every poll's answer link base and every survey's link.

func (*Service) SetPollOpen

func (s *Service) SetPollOpen(ctx context.Context, ws *store.Workspace, p *authz.Principal, pollID uuid.UUID, open bool) (PollResults, error)

SetPollOpen closes a poll now, or reopens it: answers made after reopening count as usual. Both are audited.

func (*Service) SetSurveyOpen

func (s *Service) SetSurveyOpen(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, open bool, in SurveyReopen) (Survey, error)

SetSurveyOpen closes or reopens a survey.

func (*Service) Sources

func (s *Service) Sources(ctx context.Context, ws *store.Workspace) (PollSourceList, error)

Sources lists the polls (of sent and scheduled campaigns and of drafts tested already) and the surveys of a workspace.

func (*Service) SubmitSurvey

func (s *Service) SubmitSurvey(ctx context.Context, wsID uuid.UUID, slug, token string, form url.Values) (*SurveyPage, error)

SubmitSurvey saves a survey page's answers, when the person pressed Send: scanners don't. A required question left empty saves nothing.

func (*Service) SurveyPageFor

func (s *Service) SurveyPageFor(ctx context.Context, wsID uuid.UUID, slug, token string) (*SurveyPage, error)

SurveyPageFor shows a survey page; it records nothing.

func (*Service) SurveyResultsOf

func (s *Service) SurveyResultsOf(ctx context.Context, ws *store.Workspace, id uuid.UUID) (SurveyResults, error)

SurveyResultsOf counts a survey's responses.

func (*Service) Surveys

func (s *Service) Surveys(ctx context.Context, ws *store.Workspace) (SurveyList, error)

Surveys lists the workspace's surveys, newest first.

func (*Service) Sync

func (s *Service) Sync(ctx context.Context, q *store.Queries, wsID, campaignID uuid.UUID, src string, started *time.Time, tz string) ([]Synced, error)

Sync copies the polls of a campaign's content into polls, so their links can be signed (a test send, a send). started is when the send started, nil before.

func (*Service) TestAnswers

func (s *Service) TestAnswers(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (PollTestAnswers, error)

TestAnswers lists a campaign's test answers.

func (s *Service) TestLinks(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, email string) (map[string]string, error)

TestLinks are the link variables of a test email to one address: its answers are recorded as that address's test answers, never counted.

func (*Service) TextAnswers

func (s *Service) TextAnswers(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, key, search string, offset, limit int) (SurveyTextAnswerList, error)

TextAnswers lists a text question's answers, newest first.

func (*Service) UpdateSurvey

func (s *Service) UpdateSurvey(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, in SurveyUpdate) (Survey, error)

UpdateSurvey saves a survey's changes. Settings changes are audited with before and after; editing an open survey applies to new responses.

type Survey

type Survey struct {
	ID          string           `json:"id"`
	Number      int64            `json:"number"`
	Slug        string           `json:"slug"`
	Name        string           `json:"name"`
	Description string           `json:"description"`
	Status      string           `json:"status" enum:"draft,open,closed"`
	Questions   []SurveyQuestion `json:"questions"`
	Settings    SurveySettings   `json:"settings"`
	ClosesAt    *time.Time       `json:"closesAt,omitempty"`
	PublishedAt *time.Time       `json:"publishedAt,omitempty"`
	PublishedBy string           `json:"publishedBy,omitempty"`
	ClosedAt    *time.Time       `json:"closedAt,omitempty"`
	ClosedBy    string           `json:"closedBy,omitempty"`
	CreatedBy   string           `json:"createdBy"`
	CreatedAt   time.Time        `json:"createdAt"`
	UpdatedAt   time.Time        `json:"updatedAt"`
	// URL is the public page; Variable the link variable for emails.
	URL      string `json:"url"`
	Variable string `json:"variable"`
	// Started and Completed count responses.
	Started   int64           `json:"started"`
	Completed int64           `json:"completed"`
	Linked    []SurveyLink    `json:"linked"`
	Problems  []SurveyProblem `json:"problems"`
	// CanEdit is the viewer's forms:edit; EditHelpers are members to ask
	// when they lack it.
	CanEdit     bool     `json:"canEdit"`
	EditHelpers []string `json:"editHelpers"`
}

Survey is a survey with its counts.

type SurveyClose

type SurveyClose struct {
	Mode string `json:"mode" enum:"date,manual"`
	// Date and Time are local to the survey's time zone ("2026-10-31", "23:59").
	Date string `json:"date,omitempty"`
	Time string `json:"time,omitempty"`
}

SurveyClose is when a survey stops taking answers.

type SurveyCreate

type SurveyCreate struct {
	Name string `json:"name,omitempty" maxLength:"200"`
}

SurveyCreate starts a survey.

type SurveyError

type SurveyError struct {
	Key     string
	Number  int
	Text    string
	Message string
}

SurveyError is a question that needs an answer.

type SurveyLink struct {
	CampaignID string     `json:"campaignId"`
	Name       string     `json:"name"`
	Status     string     `json:"status"`
	SentAt     *time.Time `json:"sentAt,omitempty"`
	Recipients *int64     `json:"recipients,omitempty"`
	// Via is how the email links to it: a link, or a poll that continues to it.
	Via string `json:"via" enum:"link,poll"`
}

SurveyLink is a campaign that links to a survey.

type SurveyList

type SurveyList struct {
	Items []Survey `json:"items"`
}

SurveyList is the workspace's surveys.

type SurveyOption

type SurveyOption struct {
	Key   int    `json:"key" minimum:"1"`
	Label string `json:"label" maxLength:"200"`
	// Tag is added to the contact who picks it, when the question saves tags.
	Tag string `json:"tag,omitempty" maxLength:"64"`
}

SurveyOption is one answer of a choice question.

func QuestionOptions

func QuestionOptions(q SurveyQuestion) []SurveyOption

QuestionOptions are the answers a question takes, keys included: a scale's 0–10, an emoji scale's faces, a choice's answers.

type SurveyPage

type SurveyPage struct {
	SurveyID    uuid.UUID
	Number      int64
	Slug        string
	Name        string
	Description string
	Questions   []SurveyQuestion
	Settings    SurveySettings
	ClosesAt    *time.Time
	// Closed surveys take no answers; ClosedAt is when they closed.
	Closed   bool
	ClosedAt *time.Time
	// Who answers: a contact (FirstName, Email), someone who isn't one, or a
	// test address.
	Answerer  string
	FirstName string
	Email     string
	// Refused is someone who isn't a contact, on a survey that doesn't take
	// their answers.
	Refused bool
	// Answers are the response's answers: question key → a choice's key, a
	// multiple choice's keys, a number, or text.
	Answers map[string]any
	// FromPoll is a response whose first question came from the email's
	// poll; CompletedAt an earlier completed response, editable while the
	// survey is open.
	FromPoll    bool
	CompletedAt *time.Time
	// Saved is true when this request saved the answers.
	Saved bool
	// Errors are the questions left empty, in order, with their message.
	Errors []SurveyError
	Token  string
}

SurveyPage is everything a survey page shows.

func (*SurveyPage) Error

func (p *SurveyPage) Error(key string) string

Error returns a question's message, or "".

type SurveyPath

type SurveyPath struct {
	api.WorkspaceInput
	SurveyID string `path:"surveyId" format:"uuid" doc:"Survey id"`
}

type SurveyProblem

type SurveyProblem struct {
	Question string `json:"question,omitempty"`
	Field    string `json:"field"`
	Message  string `json:"message"`
}

SurveyProblem is what keeps a survey from being published.

func SurveyProblems

func SurveyProblems(l i18n.Lang, qs []SurveyQuestion) []SurveyProblem

SurveyProblems lists what keeps a survey from being published, in a reader's language.

type SurveyQuestion

type SurveyQuestion struct {
	Key         string         `json:"key" pattern:"^q[0-9]{1,3}$"`
	Type        string         `json:"type" enum:"single,multi,scale,emoji,short,long"`
	Text        string         `json:"text" maxLength:"500"`
	Description string         `json:"description,omitempty" maxLength:"1000"`
	Required    bool           `json:"required"`
	Answers     []SurveyOption `json:"answers"`
	Save        SurveySave     `json:"save"`
	// NPS wording of a 0–10 scale, with its ends' words.
	NPS  bool   `json:"nps,omitempty"`
	Low  string `json:"low,omitempty" maxLength:"60"`
	High string `json:"high,omitempty" maxLength:"60"`
	// Faces of an emoji scale: three or five.
	Faces int `json:"faces,omitempty"`
	// RequiredText is said under a required question left empty ("Pick
	// the one closest to your job."); empty uses the type's sentence.
	RequiredText string `json:"requiredText,omitempty" maxLength:"200"`
}

SurveyQuestion is one question of a survey.

type SurveyQuestionResult

type SurveyQuestionResult struct {
	Key      string            `json:"key"`
	Number   int               `json:"number"`
	Type     string            `json:"type"`
	Text     string            `json:"text"`
	Required bool              `json:"required"`
	Answered int64             `json:"answered"`
	Counts   []PollAnswerCount `json:"counts"`
	NPS      *PollNPS          `json:"nps,omitempty"`
	// SavedTo is the field the answers fill, when they do.
	SavedTo string `json:"savedTo,omitempty"`
}

SurveyQuestionResult is one question's results over the completed responses.

type SurveyReopen

type SurveyReopen struct {
	Close *SurveyClose `json:"close,omitempty"`
}

SurveyReopen reopens a closed survey, with a new closing date or none.

type SurveyResponse

type SurveyResponse struct {
	ID          string     `json:"id"`
	CompletedAt *time.Time `json:"completedAt,omitempty"`
	// Contact is the contact's name for people with subscribers:view.
	Contact    string `json:"contact,omitempty"`
	ContactID  string `json:"contactId,omitempty"`
	NonContact bool   `json:"nonContact"`
	// Answers are the answers in words, one per question ("" unanswered).
	Answers []string `json:"answers"`
}

SurveyResponse is one completed response.

type SurveyResponseList

type SurveyResponseList struct {
	Items []SurveyResponse `json:"items"`
	Total int64            `json:"total"`
	Names bool             `json:"names"`
}

SurveyResponseList is a page of completed responses, newest first.

type SurveyResults

type SurveyResults struct {
	Started           int64   `json:"started"`
	Completed         int64   `json:"completed"`
	CompletionPercent float64 `json:"completionPercent"`
	// PollOnly answered question 1 in the email's poll and stopped there.
	PollOnly int64 `json:"pollOnly"`
	// Recipients of the emails that link to it.
	Recipients  int64                  `json:"recipients"`
	NonContacts int64                  `json:"nonContacts"`
	Questions   []SurveyQuestionResult `json:"questions"`
}

SurveyResults are a survey's completion and per-question results.

type SurveySave

type SurveySave struct {
	To    string `json:"to" enum:"none,field,tags"`
	Field string `json:"field,omitempty" maxLength:"64"`
}

SurveySave says where a question's answer goes on the contact.

type SurveySettings

type SurveySettings struct {
	Close    SurveyClose `json:"close"`
	Timezone string      `json:"timezone,omitempty" maxLength:"64"`
	// OneResponse keeps one response per contact, editable until it closes.
	OneResponse bool `json:"oneResponse"`
	// AcceptNonContacts takes answers from links without a contact's token.
	AcceptNonContacts bool   `json:"acceptNonContacts"`
	Thanks            string `json:"thanks,omitempty" maxLength:"1000"`
}

SurveySettings are a survey's settings.

type SurveyTextAnswer

type SurveyTextAnswer struct {
	Text    string    `json:"text"`
	At      time.Time `json:"at"`
	Contact string    `json:"contact,omitempty"`
}

SurveyTextAnswer is one text answer.

type SurveyTextAnswerList

type SurveyTextAnswerList struct {
	Items []SurveyTextAnswer `json:"items"`
	Total int64              `json:"total"`
	Names bool               `json:"names"`
}

SurveyTextAnswerList is a page of a text question's answers.

type SurveyUpdate

type SurveyUpdate struct {
	Name        *string          `json:"name,omitempty" minLength:"1" maxLength:"200"`
	Slug        *string          `json:"slug,omitempty" pattern:"^[a-z0-9][a-z0-9-]{0,59}$"`
	Description *string          `json:"description,omitempty" maxLength:"1000"`
	Questions   []SurveyQuestion `json:"questions,omitempty" maxItems:"20"`
	Settings    *SurveySettings  `json:"settings,omitempty"`
}

SurveyUpdate changes a survey: name, address, description, questions and settings. Omitted fields stay.

type Synced

type Synced struct {
	ID      uuid.UUID
	Number  int64
	Config  PollConfig
	Answers []Answer
}

Synced is a poll of an email after Sync: its id, number and settings.

type Visit

type Visit struct {
	UserAgent string
	IP        netip.Addr
	Method    string
	// Script is true for the page's own POST (JavaScript ran).
	Script bool
}

Visit is who opened or posted an answer page, for the classifier.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL