Collect signups with forms

Signup forms makes the forms that put an address on your lists. A form collects an email address, the other details you ask for and a tick in a box that holds your consent words. It then adds the person to its lists with its tags. A form can be a page we host, a form inside your own page, or a popup. Every form counts its views and signups, so you can see how well it converts.

• You need Tier 1 support or higher to read the forms and Tier 3 support or higher to make or change one.
• Make the lists the form should add people to first (Manage your email contacts, lists and segments). A form with no list adds people to your default list.
• Make the custom fields the form should ask for, such as a company or a birthday. A form can ask for email, First name, Last name and any custom field.
• To keep bots out, set up Cloudflare Turnstile for your account. A form asks for a challenge only when Turnstile is set up.

1. In the dashboard, open the organization, then Commerce, then Email, then Signup forms.
2. Select New form….
3. Under Details, enter a Name that only you see, and choose the Kind.
4. Choose the Fields, the Lists, tags and consent, and the Look and words, as the sections below explain. The Preview card draws the form as a visitor sees it. Its switch shows the Form, the Thanks message and the Confirm message.
5. Select Create form.

A form needs a name and consent text before it saves. After you create it, the page shows its Results and its Embed code.

Every kind also works as the hosted page, whose address is on the form's page under Embed code. For a popup, Opens chooses what shows it:

• After a delay takes a number of Seconds, from 0 to 300. It starts at 5.
• After scrolling takes a Percent of the page, from 1 to 100. It starts at 50.
• When the visitor is about to leave takes no number.

When a visitor sends or closes an embedded form, it stays away from that browser for 14 days.

The email field is always first and always required. Select Add field to add another, up to 12 fields in all. The choices are First name, Last name and each custom field of your store, marked Custom field. For each field you can set the label the visitor sees, a placeholder, and Required. Use the arrow buttons to reorder the fields below the email, and the remove button to take one out.

Lists a signup joins

The lists the form adds people to. With none ticked, a signup joins your default list.

Tags for everyone who signs up

Tags added to every contact the form makes or finds, separated by commas.

Confirmation click

Whether a new member confirms by double opt-in, an email with a link they click to join. Follow the lists asks when any chosen list asks. Always ask for a confirmation click and Never ask override the lists.

Consent text

The words shown beside the tick box, up to 500 characters. They are kept on each contact as the proof of consent. The suggested sentence names your store and says the person can unsubscribe at any time. Select Use the suggested sentence to bring it back. A signup without the box ticked is refused.

Ask visitors to pass a challenge

Asks for a Cloudflare Turnstile check. It is on for a new form. It has an effect only while Turnstile is set up for your account. Without a valid answer, a signup is refused.

Set the Heading, an optional Description, the Button label, the Thank you message and the Message when a confirmation is needed. To send people to a page after a signup instead of showing the message, enter its address under Send people to a page after signup. It must start with https://. Four colours set the Background, Text, Accent and Button text.

Open the form. Embed code holds four things, each with a copy button:

1. The hosted address. Link to it from your site, an email or a social profile. The page shows the form in your organization's name and colours, and counts a view when it opens.
2. Script tag. One tag that shows the form where the tag sits, or as a popup for a popup form.
3. Container and script. A div the form fills, then the script. Use it to choose where an inline form goes.
4. Always open as a popup. A tag that opens the form as a popup, whatever its kind.

The script needs no other file, uses no eval, and sets every style through the element, so a page with a strict Content Security Policy can run it. It counts one view for each page load.

A storefront that draws its own form calls the Store API instead, as Grow your email list shows.

When a visitor sends the form, we:

1. Check the fields, the consent box and the challenge. A missing consent answers that the box must be ticked, and a missing required field names the field.
2. Add the signup to the form's Signups.
3. Subscribe the address to the form's lists with its tags. The contact's source is form: and the form's number, and its consent record is the form's words. The consent method is popup for a popup and form for the others.
4. With double opt-in, hold the contact as Pending and email the Confirm subscription email. The contact joins the lists when its link is opened. The link works for 7 days.
5. When a list has a welcome email on, send it as the contact joins. A contact who joins starts every automation whose trigger is Fills in a form with this form, once the contact is subscribed or has confirmed (Send emails automatically with automations).

The answer is the same for an address the store knows and one it does not. An address that unsubscribed, bounced or marked an email as spam changes nothing, and the form shows its usual message. A form never tells a visitor whether the store knows an address.

A hosted or embedded signup makes a live contact when your store is live and a test contact before that. A signup posted to the Store API takes the mode of the publishable key.

Results shows the form's Views, Signups and Conversion: signups divided by views. The list of forms shows the same three figures for each form, with Active, Archived and All to filter. A popup with a view and no signup is worth another look: change when it opens, or the words.

Open the form's actions menu (Form actions) and choose Delete form… or Archive form…. The dialog asks you to type the form's name.

• A form with no views and no signups is removed.
• A form with views or signups is archived. Its page, script and Store API form stop working, and its numbers stay. Select Restore form on an archived form to turn it back on.
• A form that an automation starts on cannot be removed. Change or archive the automation first.

Every marketing email carries two links that show a page we host, in your organization's name and colours:

Unsubscribe page

Asks whether to stop marketing email from your store to the reader's address, with a button. Nothing changes until the reader presses it. Pressing it unsubscribes the contact from every list and puts the address on the suppression list. A reader who did it by mistake can tick a box that holds the sentence I want to receive marketing emails from and your organization's name, and subscribe again. A mail provider's one-click request unsubscribes at once.

Preference center

Shows the address in part, such as j***@example.com, and the lists marked Offer on the preference page as boxes, with Unsubscribe from everything. A reader ticks the lists to get and presses Save my choices. Choosing lists after unsubscribing is the reader's own consent and subscribes them again. An address that bounced or marked an email as spam is told nothing can change here. A pending address is asked to open the confirmation email first. The link works for 90 days.

The Welcome to a list email also links to the preference center.

• The form shows on your site, or at its hosted address, and each visit adds a view.
• A signup adds a Signups count and a contact with the consent words and the source form: and the form's number.

The form does not appear on my site

The page may block the script, or the form is Archived. Check the form's status, and that your page holds the tag exactly as Embed code shows it.

A signup is refused and asks for the consent box

The visitor did not tick it. A form always asks, and the answer says the box must be ticked.

A signup is refused with a challenge error

The form asks for a Turnstile check and the visitor did not pass it. Check that Turnstile is set up for your account, or turn off Ask visitors to pass a challenge.

A contact stays Pending

The list or the form asks for a confirmation click and the contact has not clicked. The link works for 7 days. A new signup after 10 minutes sends another.

Views stays at 0

The page or script was not opened, or the storefront's own form never reports its views. Call POST /store/marketing/forms/{public_id}/views when the form shows.

Create form or Save changes names a field

The message says what to fix, such as a colour that is not #rrggbb or a redirect that does not start with https://.

• Manage your email contacts, lists and segments
• Send emails automatically with automations
• Build a checkout with the Store API
• Collect and export your store's leads

The routes are under https://api.coritan.com/api/v1/orgs/{org_slug}/marketing/forms. Reading takes marketing.campaigns:read and changing takes marketing.campaigns:write (API key scopes).

GET /forms/catalog lists what a form can use: the kinds, the fields (built in and your custom fields, with their input type), max_fields, the popup_triggers, the default_design and the default_consent_text.

POST /forms makes a form and answers 201 with {form}:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/marketing/forms" \
  -H "X-API-Key: $ORG_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Footer signup", "kind": "inline", "list_ids": [3], "tag_names": ["footer"],
       "consent_text": "I agree to get emails from Acme. I can unsubscribe at any time.",
       "fields": [{"key": "email", "required": true}, {"key": "first_name", "label": "Your name"}],
       "design": {"heading": "Join our list", "button_label": "Sign me up"}}'

A form is {id, public_id, name, kind, status, list_ids, tag_names, fields, consent_text, double_opt_in, design, turnstile, views, submissions, conversion_rate, hosted_url, created_at, updated_at}. public_id is what a storefront and the hosted address use. status is active or archived.

• GET /forms lists forms, newest first, as {total, limit, offset, forms}. status filters by active or archived, and kind by inline, popup or page.
• GET /forms/{form_id} answers one form.
• PATCH /forms/{form_id} changes what you send. design is merged into the stored design key by key, and status is active or archived.
• DELETE /forms/{form_id} removes a form nobody has seen and answers {deleted: true, id}. A form with views or signups is archived and answers {deleted: false, archived: true, id}. It answers 409 with form_in_use while an automation starts on it.
• GET /forms/{form_id}/embed answers {hosted_url, script, html, popup_script}, the four pieces of code under Embed code.

A refused setting answers 422 with invalid and a field that names it, such as design.colors.accent or fields[1].key.