Manage your email contacts, lists and segments

Contacts lists the people you can email, Lists holds the lists they join with the custom fields and tags that describe them, and Segments and Import are two views of Contacts. A contact is an email address with a status, the lists it is on, and the record of the consent it gave.

• You need Tier 1 support or higher to read contacts, lists, fields, tags and segments, and Tier 3 support or higher to change them. Import opens for Tier 3 support and above only.
• Your store needs no setup to hold contacts, but nobody is emailed until the sending domain is ready.
• Contacts belong to a mode. A store in test mode makes test contacts, and a live store makes live contacts. The list shows both, and a campaign mails the contacts of its own mode (Set up email marketing for your store).

A contact comes from one of these, and Source says which:

The Any source filter lists the named sources only, so it does not find a contact whose source is form:3. A shopper who turns marketing off in their account, or unsubscribes from any store email, becomes Unsubscribed here too. The two stay in line.

1. In the dashboard, open the organization, then Commerce, then Email, then Contacts.
2. Type part of a name or an address in Search by name or address.
3. Narrow the list with Any status, Every list, Any tag, Any segment and Any source. The statuses are Subscribed, Pending, Unsubscribed, Bounced and Marked as spam.
4. Choose how to sort under Sort by: Newest first, Address, A to Z or Most engaged first.

The list shows 50 contacts a page, with the Contact, its Status, Tags, Lists, Engagement, Source and the date it was Added. Every filter is kept in the page address, so a reload or a shared link opens the same list. The count above the list says how many contacts match.

Add a person only when you hold their consent already.

1. On Contacts, select Add contact….
2. Enter the Email, and optionally the First name and Last name.
3. Under Consent, choose Subscribed or Pending. Subscribed adds the person to the lists you tick at once. Pending emails them a confirmation link, and they join the lists when they click it.
4. Under Words they agreed to, write what they agreed to. It is kept as the record of consent. Leave it empty to record that you added them.
5. Tick the Lists and enter any Tags, separated by commas, then select Add contact.

With no list ticked, the contact joins the default list. An address that is already a contact answers This address is already a contact, with a link to it. An address on the suppression list is added with the status it is held under, and nothing is ever mailed to it.

Select a contact to open its page. Profile holds the names, the email address and your custom fields, and Save changes keeps an edit. The other cards are:

Timeline

What happened to the contact, newest first: signups and confirmations, emails sent, delivered, delayed or failed, opens, clicks, bounces, spam reports, unsubscribes, orders, lists joined and left, and consent. A click names the campaign and the link. Show older pages back. An open or a click made by a mail privacy tool is marked automatic.

Consent

The words the contact agreed to, when and how, and where the contact came from. When the contact is not subscribed, it also shows when and why it stopped. A contact with no consent on record shows a warning, so check how it was added before you email it.

Lists and Tags

The lists the contact is on, with Add to list… for a subscribed contact, and its tags, with Add tag.

Engagement

The engagement score, a figure from 0 to 100 for how often the contact opens and clicks. Opens add up to 40 points and clicks up to 60, with ten opens and five clicks giving the most, and both fade to nothing over 90 days. Opens by mail privacy tools do not count. The card also shows emails received, opens, clicks, and when the last email, open and click were.

On a contact that is Subscribed or Pending, Unsubscribe… takes it off every list. That is your own decision for the contact, so only the contact's own signup brings it back. No control in the dashboard resubscribes anyone.

A contact that bounced or marked an email as spam shows an alert. Its address is on the suppression list, and no campaign or automation sends to it. Nobody can lift that.

1. On Contacts, tick the contacts, or tick the box in the header to pick the page. To pick every contact the filters match, select the Select all link that names how many match.
2. Select Bulk actions.
3. Choose Add a tag…, Remove a tag…, Add to a list…, Remove from a list…, Unsubscribe… or Delete….

Only subscribed contacts join a list. A pending, unsubscribed or bounced contact is skipped. Delete… asks you to type delete and can also erase, as the next section says. One action changes at most 100,000 contacts, or 10,000 for Unsubscribe… and Delete…. Narrow the filters when you reach the limit.

Export CSV downloads every contact the filters match, up to 100,000. With no filter set, it exports your whole audience. The columns are id, email, first_name, last_name, status, tags, lists, source, consent_text, consent_at, consent_method, subscribed_at, unsubscribed_at, unsubscribe_reason, livemode, created_at and one fields.<key> column for each custom field. A file with these headers imports back. A text cell that starts with =, +, - or @ starts with an apostrophe, so a spreadsheet shows it as text. Each export is recorded in the audit log.

To answer a person who asks what you know about them, open their contact, open its actions menu (Contact actions) and choose Download data (JSON). The file holds the contact and its consent, tags, lists, events, emails received, its suppression entry, and the lead and customer with the same address.

To remove a person, open the same menu and choose one of:

• Delete contact… removes the contact, its list memberships and its tags. The emails it received stay in their campaigns' reports.
• Erase contact… also removes its events and its address from those emails.

Both ask you to type the contact's address, and neither can be undone. The suppression entry stays after either, so an address that unsubscribed is never mailed again.

Consent is the record of what a person agreed to. A contact is subscribed only after it agreed, and the record stays after it unsubscribes. Collect signups with forms covers the words a form shows.

A list can ask for double opt-in: the person gets an email with a link and joins the list only when they click it. That proves the address is theirs, and it is the safest way to collect signups. Until they click, the contact is Pending and gets no campaign. The link works for 7 days, and the email is the Confirm subscription email (Write the emails your store sends). A person who signs up again while waiting gets a new link only after 10 minutes.

A signup from an address that unsubscribed, bounced or marked an email as spam changes nothing, and the form shows its usual thank you message, so a form never tells a visitor whether the store knows an address.

An unsubscribed contact can come back only on its own: from the page it reaches after unsubscribing, from its preference center, or by turning marketing on in its storefront account. An address that bounced or marked an email as spam cannot come back.

1. Open the organization, then Commerce, then Email, then Lists.
2. Select New list…, enter a Name and optionally a Description, tick New members confirm by email first if the list needs a confirmation click, then select Create list.

Lists shows each list with its Subscribed, Pending and Unsubscribed counts and the joins of the last 14 days. Active and Archived switch the view. The first list a store makes becomes the default list, called Newsletter when the store makes it for you. A signup that names no list goes to the default list.

Select a list to open it. The page shows Growth for 14, 30 or 90 days, the Members (newest first, with the date a member left), and Settings:

Select Save changes after an edit. Archive list… hides a list from signups, the preference page and the campaign picker, and keeps its members and history. Restore list brings it back. Delete list… removes a list nobody was ever on. For a list with members, the dialog offers to archive it instead. The default list can be neither archived nor deleted: make another list the default first. To take one contact off a list, use Remove from list… on the contact or on the list's Members. The contact stays on its other lists.

A custom field holds something else you know about a contact, such as a company or a birthday. On Lists, the Custom fields card lists them. Select Add field… and fill in:

The key and the type cannot change after the field exists. A store can have up to 100 custom fields. Delete field… asks you to type the key and removes the value from every contact that holds one. Merge tags and segment rules that use it stop matching.

A tag is a free label, up to 64 characters, that you put on contacts to find them again or to start an automation. On Lists, the Tags card lists them with how many contacts carry each, and Add tag… makes one with a Name and a Colour that only you see. A tag is also created the first time you put it on a contact. A contact can carry up to 100 tags. Delete tag… takes the tag off every contact that carries it.

A segment is a saved set of rules that picks contacts. The people it holds change as contacts change, so a campaign sent tomorrow uses tomorrow's matches.

1. On Contacts, choose Segments, then select New segment….
2. Enter a Name, and optionally a Description.
3. Under Rules, the first group reads "Contacts match", a choice of all or any, and "of these rules". Choose one, then select Add rule and pick a field, an operator and a value.
4. Select Add group to nest a group of rules inside. Groups nest up to three levels deep, and a segment has at most 50 rules.
5. Watch Who matches. It counts the contacts the rules match after a short pause, shows a sample of the newest ten, and says contacts match. Select Create segment.

The count includes contacts of every status, whatever the rules say about status. A campaign sends only to the subscribed ones among them. To count only people you can email, add the rule Status is subscribed.

The segment list shows each segment's Contacts count as it was when last counted. Count again counts it now. See the contacts opens Contacts filtered to the segment. Edit rules opens the builder. Delete segment… asks you to type its name. A segment that a scheduled, sending or paused campaign, or an automation that is on, still uses cannot be deleted. The message names where it is used.

Each rule is a field, an operator and a value. The builder groups the fields:

The operators follow the field's type:

• Order facts match a contact to its orders by customer or by email address, in the contact's own mode, and leave cancelled orders out. Total spent and Average order are in the smallest unit of the order's currency, such as cents, after refunds.
• Opened a campaign and Clicked a campaign leave out opens and clicks by mail privacy tools and link scanners.
• Received a campaign means the email reached the contact's server.

Import brings an audience in from a file or from EmailOctopus. Both end in a dry run, a trial that reads everything and counts what would happen without adding or changing a single contact. Only then can you run the import for real.

1. On Contacts, choose Import. Or select More contact actions, then Import contacts….
2. Choose CSV file or EmailOctopus.

An import never subscribes an address that unsubscribed, bounced or marked an email as spam, or one that is on the suppression list. It sends no email, starts no automation and sends no webhook.

The file needs a header row and one contact on each row. It can be up to 15 MB and 200,000 rows, in UTF-8 or Latin-1, with commas, semicolons or tabs between columns.

1. Step 1 of 4: Choose a file. Select Choose a CSV file… and pick the file.
2. Step 2 of 4: Match the columns. For each column, choose what it Holds: Email address, First name, Last name, Tags (separated by commas or semicolons), Status, Custom field, or Do not import. We suggest a match from the header and the first rows. Exactly one column must be the email address. Optionally choose A column that marks a row unsubscribed: a row with a yes, true or 1 in it is imported as unsubscribed and its address is suppressed. Select Continue.
3. Step 3 of 4: Choose where they go. Pick the List the contacts join, optionally enter Tags for every contact, and select Start dry run.
4. Step 4 of 4: Check, then run. Read the counts. Under Run it for real, choose Add new contacts only or Add new and update existing, tick I hold these contacts' consent to email them, and select Run import.

Switch from EmailOctopus walks through this wizard, and what comes over.

An EmailOctopus import also counts Lists, Tags and Fields. Import history lists every import and dry run, newest first. Select one to open its own page, with its counts, the first 200 problems under Problems with the row and the reason, and Cancel import… while it runs. What a cancelled import already added stays. A file of up to 1,000 rows finishes at once. Larger imports run in the background and the page updates by itself.

A dry run keeps its file for 24 hours. After that, a run answers that it has expired, and you upload the file again. A real run needs your confirmation of consent, and it records Imported from a file. The person importing it confirmed the contacts' consent. as the contacts' consent.

Leads and customers who agreed to marketing before email marketing existed are not contacts yet. Open More contact actions, then Bring in leads and customers…, to turn them into contacts on your default list:

• A lead that gave consent becomes a subscribed contact, with the words it agreed to.
• A customer who accepts marketing becomes a subscribed contact linked to their account.
• An address on the suppression list stays suppressed.

It tells you how many were added, updated and skipped. You can run it again: a contact that already has what it would be given is skipped. It allows 6 runs an hour. A lead or a customer who agrees after you run it joins by themselves.

• A contact appears in the list with its status, lists and tags as soon as it is added or imported.
• A Subscribed contact on a list receives that list's campaigns.
• A contact that unsubscribes, bounces or marks an email as spam leaves every list at once.

Add contact… says the address is already a contact

The address is in the store in this mode. Open the contact from the link, or use Add new and update existing when you import.

A contact I added never gets email

It is Pending until it confirms, or Unsubscribed, Bounced or Marked as spam, or its address is on the suppression list. Open the contact and read its Timeline and Consent.

A bulk action says it changed fewer contacts than I picked

Add to a list… skips contacts that are not subscribed. Other actions skip contacts the change does not apply to, such as removing a tag a contact does not have.

Export CSV says to narrow the export

More than 100,000 contacts match. Filter by list, tag, status or date, and export in parts.

Import says the dry run expired

A dry run keeps its file for 24 hours. Upload the file again. For EmailOctopus, send the API key again.

A segment cannot be deleted

A scheduled, sending or paused campaign, or an automation that is on, uses it. The message names which. Change or cancel that first.

The Import view is missing

Importing needs Tier 3 support or above.

• Set up email marketing for your store
• Collect signups with forms
• Write, test and send email campaigns
• Collect and export your store's leads
• Win back shoppers with marketing emails

The routes are under https://api.coritan.com/api/v1/orgs/{org_slug}/marketing/. Reading takes marketing.contacts:read and writing takes marketing.contacts:write (API key scopes). Another organization's contact is not found, and every write is recorded in the audit log without the contact's address.

GET /contacts lists contacts and answers {total, limit, offset, contacts}. Its filters are q, status, list_id, tag, segment_id, source, since (included) and until (not included) on the day the contact was added, and livemode. sort is created (newest first), email or engagement, and order is asc or desc.

curl "https://api.coritan.com/api/v1/orgs/acme/marketing/contacts?status=subscribed&tag=vip&sort=engagement" \
  -H "X-API-Key: $ORG_API_KEY"

POST /contacts adds a contact and answers 201 with {contact}:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/marketing/contacts" \
  -H "X-API-Key: $ORG_API_KEY" -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "first_name": "Alex", "status": "subscribed",
       "consent_text": "Signed up at the shop counter.", "tags": ["counter"], "list_ids": [3]}'

A contact is {id, email, first_name, last_name, status, fields, tags, list_ids, customer_id, source, livemode, consent, subscribed_at, unsubscribed_at, unsubscribe_reason, stats, created_at, updated_at}. status is subscribed, pending, unsubscribed, bounced or complained. consent is {text, at, method}, and stats holds emails_received, opens, clicks, the last send, open and click times, and engagement_score. An address that is already a contact in this mode answers 409 with contact_exists and the contact's id.

• GET /contacts/{contact_id} answers {contact, lists}, where lists holds each list's id, name, the membership's status and when the contact joined.
• PATCH /contacts/{contact_id} changes email, the names, fields (merged, and null clears a key) and tags (the contact ends up with exactly the tags sent). status can only become unsubscribed. It can never go back to subscribed this way.
• DELETE /contacts/{contact_id} deletes the contact, and ?erase=true also removes its events and its address from emails it got. It answers {deleted: true, id}.
• GET /contacts/{contact_id}/timeline?limit&before answers {events}, newest first. Send the last entry's at as before for the next page.
• GET /contacts/{contact_id}/export answers everything held about the contact as a JSON file. GET /contacts/export answers the CSV, with the same filters as the list. It allows 30 exports an hour, and refuses more than 100,000 rows with 422 and too_many.
• POST /contacts/bulk takes ids (up to 5,000) or a filter with the list's filters, and an action: tag, untag (with tag), add_to_list, remove_from_list (with list_id), unsubscribe or delete (erase: true also erases). It answers {affected}. An empty filter means every contact.
• POST /contacts/backfill brings in leads and customers and answers {created, updated, skipped}. Add ?livemode= to limit it to one mode.

• GET /lists answers {total, limit, offset, lists}, the default first, with each list's counts of subscribed, pending and unsubscribed. ?archived=true lists the archived ones. POST /lists makes one. GET, PATCH and DELETE /lists/{list_id} read, change and delete one. A list has name, description, double_opt_in, confirmation_subject, confirmation_body, welcome_enabled, welcome_subject, welcome_body, public, is_default and archived. A name another list has answers 409 with list_exists.
• DELETE /lists/{list_id} answers 409 with list_in_use for a list with members. ?force=true archives it. The default list answers 409 with default_list.
• GET /lists/{list_id}/stats?days=30 answers {counts, growth}, with {date, joined, left} for each day, up to 365 days.
• GET /lists/{list_id}/members?status&q lists the members, each with its membership. POST /lists/{list_id}/members takes contact_ids or emails, up to 1,000 of each, and answers {added, skipped, not_found}. DELETE /lists/{list_id}/members/{contact_id} takes a contact off the list.
• GET /fields lists custom fields. POST /fields takes key, label, type (text, number, date, boolean or choice), choices and default_value. PATCH changes the label, choices, default value and position. DELETE /fields/{field_id} answers {deleted, id, contacts_cleared}.
• GET /tags lists tags with contacts counts, and ?q= filters by name. POST /tags takes a name and a color such as #c0392b. PATCH renames or recolours. DELETE /tags/{tag_id} answers how many contacts carried it. A name another tag has, in any case, answers 409 with tag_exists.

A segment's rules are {"match": "all", "rules": [rule or group]}, where a rule is {"field", "op", "value"}:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/marketing/segments/preview" \
  -H "X-API-Key: $ORG_API_KEY" -H "Content-Type: application/json" \
  -d '{"rules": {"match": "all", "rules": [
        {"field": "tag", "op": "has", "value": "vip"},
        {"field": "last_open_at", "op": "within_days", "value": 30}]}}'

The answer is {count, sample}. GET /segments/fields lists every field with its operators, each with a key, a label and whether it needs_value. Add ?campaigns=true to list your sent campaigns as choices. POST /segments saves a segment from name, description and rules, and answers 201 with {segment}, which holds count and counted_at. A name another segment has answers 409 with segment_exists. A refused rule answers 422 and names it in field, such as rules.rules[2].op. PATCH /segments/{segment_id} changes it, and changing the rules counts it again. POST /segments/{segment_id}/refresh answers {count}. GET /segments/{segment_id}/contacts lists the matches. DELETE answers 409 with segment_in_use and used_by while a campaign or an automation uses it.

Every import route takes marketing.contacts:write, reading an import included.

1. POST /imports/csv/preview takes the file as the multipart field file and answers columns, a sample, total_rows, the delimiter and encoding it read, and a suggested_mapping from each column to email, first_name, last_name, tags, status, field:<key> or null.

2. POST /imports starts the import and answers 202 with {import}. For a file, send the multipart fields file and options, a JSON text. Send mode: "dry_run" first.

   Shell

   curl -X POST "https://api.coritan.com/api/v1/orgs/acme/marketing/imports" \
     -H "X-API-Key: $ORG_API_KEY" \
     -F "file=@contacts.csv" \
     -F 'options={"mapping": {"Email": "email", "First name": "first_name", "Tags": "tags"}, "list_id": 3, "tags": ["imported"], "mode": "dry_run"}'
   

3. GET /imports/{import_id} reads the progress. An import is {id, kind, status, mode, list_id, options, total, processed, counts, errors, error, started_at, completed_at, created_at}. status is pending, running, completed, failed or canceled. counts holds created, updated, skipped, suppressed, invalid, duplicates, lists, tags and fields, and errors holds the first 200 problems as {row, email, error}.

4. POST /imports/{import_id}/run turns a finished dry run into a real run. Send {"mode": "create_only", "consent_confirmed": true}, or "mode": "upsert" to update known contacts too. Without consent_confirmed the answer is 422 with consent_required. Another kind of import answers 409 with not_a_dry_run, and a dry run older than 24 hours answers 409 with expired.

5. POST /imports/{import_id}/cancel stops a pending or running import. A finished one answers 409 with import_finished.

mode is dry_run (the default), create_only or upsert. GET /imports lists the imports, newest first.

For EmailOctopus, POST /imports/emailoctopus/lists answers {lists} with each list's id, name, subscribed, unsubscribed, pending, fields and tags. Send the account's api_key, or leave it out to use the key of the store's EmailOctopus integration. A key EmailOctopus refuses answers 422 with emailoctopus_key_refused. Then start the import with JSON:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/marketing/imports" \
  -H "X-API-Key: $ORG_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind": "emailoctopus", "mode": "dry_run", "list_ids": ["5c4f3b2a-1d0e-4a9b-8c7d-6e5f4a3b2c1d"], "options": {"tags": ["imported"]}}'

The API key is sealed on the import and removed when it ends. An import starts at most 30 times an hour.