Surveys

Surveys sends one of your forms to a chosen audience, gives each person their own link, and shows who has answered and what they said. Open it from Surveys in the admin sidebar (Surveys).

What it does

• A survey uses a form you build in Data > Forms. The form's questions are the survey's questions.
• You keep an audience of contacts, sorted into groups. A survey invites the contacts in the groups you pick.
• Each person gets an email with a personal link. Their code works once: one answer per invitation.
• Surveys can be Identified or Anonymous. In an anonymous survey the answer is stored without who gave it.
• The results screen shows the response rate and a question-by-question summary, and exports the answers as CSV or JSON.
• Reminders go to people who have not answered: by hand at any time, or automatically if you set up a scheduler (see "Automatic reminders").
• Every invitation and reminder ends with "Don't want these emails? Unsubscribe" (and carries the headers that give mail apps their own Unsubscribe button). The unsubscribe list is shared: someone who opts out here gets no more Campaigns, Surveys or Onboard reminder emails from the site. The link needs the Site URL setting (System > Site Settings); without it emails go out with no unsubscribe link.

Getting started

1. Check the site can send email: System > Site Settings > Email needs your SMTP details. Invitations are sent through them. Also set Site URL on the General tab (for example https://example.com): the personal links in the emails are built on it.
2. Build the questions as a form in Data > Forms.
3. Open Surveys and press Audience in the banner.
4. Type a group name (for example customers) in New group name... and press Add.
5. Press Add contact in the banner. Enter a Name, an Email and tick the group. Press Add contact at the bottom of the panel. Repeat for each person, or use Import from Contacts (see below).
6. Go back to the list (All surveys in the banner) and press New survey.
7. Enter a Title, check the Slug, and choose the Form.
8. Under Audience & status, tick your group under Audience groups, and set Status to Open.
9. Fill in the invitation email (or leave it empty for a plain default one). Press Save (Ctrl+S).
10. In the Invitations section at the bottom, press Send invitations.

Screens

Surveys list

Every survey, with its slug, form, how many have answered, its schedule and its response rate.

• All, Open, Drafts, Closed - filter by status. Each shows a count.
• Search surveys... - find a survey by name.
• Sort by Latest activity, Title or Response rate.
• Click a survey to edit it.
• Right-click a survey (or use its menu button, or Shift+F10) for:
  • Edit
  • Results
  • Open or Close... - closing stops its links taking answers.
  • Send invitations... - to everyone in its groups who has not answered. Open surveys only.
  • Send a reminder... - to everyone invited who has not answered. Open surveys only, once someone has been invited.
  • Copy embed shortcode - see "Shortcodes" below.
  • Duplicate... - a copy with a new title and slug, saved as a draft.

Banner buttons: Audience and New survey.

Survey editor

Opened by New survey or by clicking a survey. Banner buttons: All surveys, Results (existing surveys) and Save (Ctrl+S).

A bar at the top shows Unsaved changes. with Discard and Save. If you leave with unsaved changes you are asked first, and your changes are kept as a draft that is offered back on your next visit.

The survey

• Title - required.
• Slug - the survey's address, /survey/<slug>. Made from the title as you type. Lowercase letters, numbers and hyphens (the server checks this too, and that the form exists). It cannot change once the survey is saved.
• Form - the form respondents fill in. Answers are stored with that form's submissions, tagged with this survey.
• Description - for you only. Respondents do not see it.

Audience & status

• Status - Draft: nothing is sent and links do not work. Open: invitations can go out and answers are taken. Closed: links stop taking answers.
• Mode - Identified or Anonymous.
• Audience groups - tick the groups to invite. The hint below says how many contacts that is.

Schedule

• Opens and Closes - optional dates. Answers are taken from the start of the Opens day to the end of the Closes day, in the site's time zone (the Time zone setting - UK time unless you change it). After the Closes day the survey's page says it has closed, answers are refused, and no invitations or reminders can be sent until you move the date. Before the Opens day the page says when it opens.
• Reminder after (days) - how long after an invitation a person counts as due a reminder. The default is 7. This only matters if you set up automatic reminders.

Survey page

What respondents see around the form. Markdown works in the intro and footer.

• Intro - above the form.
• Footer - below the form.
• Thank-you message - shown after they submit. Empty shows "Thank you - your survey response has been recorded."

Invitation email

• Subject - empty uses "You are invited to a survey".
• Body - {{name}} becomes the person's name and {{link}} their personal link, shown as a Take the survey button. The email also shows the link as text below the button. Empty uses a short default message.

The sender name is the one in your site's email settings; if that is empty, the From name plugin setting is used.

Invitations (existing surveys only)

• Send invitations - emails everyone in the audience groups who has not answered yet.
• Remind non-responders - emails everyone who was invited and has not answered.

Both buttons work only when the saved survey is Open and there are no unsaved changes. Save first: sending uses the saved survey. A message then says how many were sent, for example "12 of 12 sent."

Every send gives each person a fresh code. The link in any earlier email for that survey stops working - the latest link wins. People who have already answered are never emailed again.

Audience

Everyone a survey can invite. This is the shared outreach audience: Surveys and Campaigns use the same contacts and groups. It is separate from the Contacts tool, though Import from Contacts copies people across.

• Contacts (left) - search by name, email or group. Click a contact, or right-click it, for Copy email and Delete.... Deleting a contact does not stop invitations already sent.
• Groups (right) - click a group to show only its contacts. Type a name in New group name... and press Add to make one.

Banner buttons:

• All surveys - back to the list.
• Add contact - Name, Email (required) and Groups. Add the group first, then give it to contacts.
• Import from Contacts - copies your own contacts from the Contacts tool (with their groups) into the audience. Contacts without an email are skipped. This button is hidden when the Contacts tool is switched off on the site.

Results

Opened from a survey's Results menu item or the editor's Results button.

• The survey's title, status, and an Anonymous tag if it is anonymous.
• Response rate, Invited, Answered and Waiting (invited but not answered yet).
• Question by question - choice and rating questions show how the answers split; free-text questions list every answer. Only answers given through this survey count; other submissions to the same form are left out.

Banner buttons: All surveys, Edit survey, Export CSV, Export JSON and Refresh. In the CSV, an answer that begins with =, +, - or @ is written as text (with a leading apostrophe) so a spreadsheet never runs it as a formula.

What respondents see

The link in the email opens /survey/<slug> on your site with the person's code already filled in. If they arrive without it, they can type the code from their email (it looks like ABCD-EFGH).

• A survey that is not Open, or whose Closes day has ended, shows "This survey has closed."
• Before its Opens day, the page says the date it opens.
• A code that has already been used is refused.
• The form's own required fields and checks apply.
• If the form has email notifications switched on in Data > Forms, each survey answer sends that notification too.

Automatic reminders

Reminders are not sent on their own. Reminder after (days) does nothing until something outside the site asks for reminders to be sent. Without that, send reminders by hand with Send a reminder... or Remind non-responders.

To send them automatically you need a scheduler that can make web requests - for example a cron job on a server, or a hosted cron service.

1. Set the scheduler token

1. Make up a long random string (32 characters or more). This is the token.
2. On any Surveys screen, click the Surveys settings cog in the banner.
3. Paste the string into Scheduler token and press Save. It works at once - no restart.

The token is shown masked after saving (only its last four characters); leave the masked value as it is to keep it.

While Scheduler token is empty, the scheduler addresses refuse every request.

2. Set up the scheduler

Run it once a day. Each run makes two kinds of request, both with the header Authorization: Bearer <your token>:

1. GET https://your-site/api/plugins/surveys/due-work - lists open surveys with people due a reminder, for example [{"plugin":"surveys","campaignSlug":"customer-sat-q3","dueCount":4}]. A person is due when they were sent an invitation or reminder at least Reminder after (days) ago and have not answered.
2. For each survey in that list: POST https://your-site/api/plugins/surveys/run with the JSON body {"campaignSlug":"customer-sat-q3"}.

/run sends a reminder to everyone in that survey who was invited and has not answered, each with a fresh link, and restarts their reminder clock. So a person gets at most one reminder every Reminder after (days) days until they answer or the survey closes.

An example for a Linux cron job (needs curl and jq):

TOKEN='your-token'
SITE='https://example.com'
curl -s -H "Authorization: Bearer $TOKEN" "$SITE/api/plugins/surveys/due-work" \
  | jq -r '.[].campaignSlug' \
  | while read -r slug; do
      curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
        -d "{\"campaignSlug\":\"$slug\"}" "$SITE/api/plugins/surveys/run"
    done

Use your site's public address in these requests. The personal links in the emails are built on the Site URL setting (System > Site Settings, General tab). Only if that is empty are they built from the address the scheduler calls, so an internal address would end up in the emails.

Keep the token secret: anyone with it can make the site send reminders.

Settings

Click the Surveys settings cog in the banner of any Surveys screen. Only people allowed to delete surveys can open it. Changes take effect as soon as you press Save - no restart.

• From name - the sender name for invitations when your site's email settings have none. Default "Surveys".
• Time zone - the time zone the Opens and Closes days are in, as a name like Europe/London (the default) or America/New_York. The cog warns about a name it does not recognise; one the site does not know counts as Europe/London.
• Scheduler token - see "Automatic reminders". Empty switches the scheduler off.

Storage is still set in the Marketplace (click Surveys in the Installed list) - leave it as it is.

Shortcodes

Put a survey inside any page:

[survey slug="customer-sat-q3" /]

Copy embed shortcode (in a survey's menu) copies exactly this, ready to paste. Typed by hand, it must end with /], or it shows on the page as text.

The embedded survey still needs a personal code. It shows the form only when the page's address carries the code (?t=ABCD-EFGH). Otherwise it asks the visitor to use the personal link from their invitation. The invitation emails always link to /survey/<slug>, not to your page.

Permissions and roles

Surveys adds one permission, Surveys (group Plugins), in System > Roles:

Action	Label	Allows
surveys.read	View	See surveys, the audience and results; export answers
surveys.create	Create	Create and duplicate surveys; add contacts and groups; import from Contacts
surveys.update	Edit	Edit surveys, open and close them, send invitations and reminders
surveys.delete	Delete	Delete audience contacts

The Admin role has all four by default. Other roles get none until you tick them.

Tips

• Try a new survey on yourself first: put your own address in a test group, send, and answer it.
• Importing from Contacts twice adds the same people twice, and a person listed twice gets two emails. Check the audience before sending.
• The Surveys sidebar badge counts responses in the last 7 days. Its popover lists open surveys and those closing soon.
• Notifications: "Survey responses" (one notice per survey per day, updated as more arrive) and "Surveys closing soon" (each morning, for open surveys closing within 3 days).
• In an anonymous survey, the invitation still records that a person has answered, and when. With very few respondents the timing can give someone away, so do not promise perfect anonymity.

Limitations

• There is no way to delete a survey. Close it instead. Its answers stay with the form's submissions.
• Contacts cannot be edited. To change a contact's name, email or groups, delete them and add them again.
• Groups cannot be renamed or deleted.
• Reminders are only automatic with an external scheduler and the scheduler token.
• A Reminder after (days) of 0 is treated as 7.
• Every answer needs a personal code: there is no open survey anyone can answer without an invitation.