Contacts, lists and consent

Contacts are the people a tenant knows by e-mail or by its own id: customers, leads, newsletter subscribers. They are the base for e-mail campaigns and, later, Snakkbar's CRM. Everything here is reachable through the server API, so a tenant's own systems (a CMS, an ERP such as Business Central, a CRM) keep Snakkbar in sync themselves. Snakkbar ships no connector for any of them.

In the panel (Mailbar → Kontakter, a list or «Alle kontakter»), people are added one at a time («Legg til kontakt», with the list and basis), imported from Excel (.xlsx, the first sheet) or CSV, and exported as either. An export's first columns carry the import's own headings (E-post, Fornavn, Etternavn, Firma, Telefon, Stilling, Ekstern ID), so it can be edited and imported again as it is; a list's export adds each contact's status and basis on it. CSV is written with ; and a byte order mark, as Excel in Norway expects, and a field that starts like a formula gets a leading '.

Moving from Mailchimp (Innstillinger → Import → «Flytt fra Mailchimp», admins): paste a Mailchimp API key (Profile → Extras → API keys), tick one or more audiences («Merk alle» / «Fjern alle»), pick a list for each (an existing one, else a new list named after the audience), and map their fields once (to contact fields or attributes). A single audience can also bring its groups and tags (each to a list of its own, an attribute, or left out). Snakkbar then reads the audiences one after the other over Mailchimp's Marketing API in the background:

• subscribed members go on their audience's list with the basis you choose and Mailchimp's own record as proof per person (when, from which IP, how they signed up);
• unsubscribed members are unsubscribed from that list only: an unsubscribe in Mailchimp is per audience, so the address stays open for the other lists;
• cleaned (bounced) addresses are blocked for every e-mail, so no later import or sync adds them back.

Someone in several audiences is one contact on several lists. Nothing is written to Mailchimp. «Flytt flere publikum» moves more audiences later with the same key (the ones moved are marked). «Hent endringer» reads every audience moved so far, each only for members changed since it was last read (switch-over day); «Koble fra» forgets the key, which is kept encrypted until then. Operator API: GET /operator/mailchimp, POST /operator/mailchimp/connect { apiKey }, GET /operator/mailchimp/imports/:id/audiences, GET …/imports/:id/fields?audiences=a,b, POST …/imports/:id/start (MailchimpMappingInput { audiences: [{ id, list }], basis, fields, interests?, tags? }), POST …/imports/:id/changes, DELETE …/imports/:id/key.

A visitor (a browser on the site) is not a contact. A visitor your backend identifies with POST /server/visitor-tokens and an email is linked to the contact with that address, so their visits and chats can be shown on the contact.

#Consent rules

Every subscription has a basis:

The legal judgement is the tenant's. Snakkbar stores the basis and the proof and enforces four rules:

1. Unsubscribing always works, from any source.
2. An unsubscribe wins over a sync. Once someone unsubscribed, from that list or from everything (or was blocked by hand), subscribing them again needs basis: "consent"; a nightly sync that still says "customer" gets 409 for that contact. Fresh consent lifts the suppression when the status is subscribed; a pending sign-up does not (confirmation mails come with the e-mail module).
3. An import never subscribes them again, whatever basis it claims: a file (/contacts/bulk) or a Mailchimp move leaves someone who unsubscribed from the list, or from everything, as they are, and says so per row. Only the person can sign up again (or a single call with their fresh consent). With subscribe.skipUnsubscribed, an import also leaves out anyone who has unsubscribed from any list before (subscriptionSkipped: "unsubscribed_before"); the panel's import has it on by default.
4. Bounced and complained addresses cannot be subscribed again at all.

A change to the same status and basis is a no-op: a sync that sends the same data every night logs nothing and fires no events.

#Authentication and scopes

All endpoints take a secret API key (Authorization: Bearer sk_snakkbar_…, see api.md). Reading needs the contacts:read scope, anything that changes data needs contacts:write (which includes reading). Give an integration only what it needs: a newsletter sign-up form on the website needs contacts:write and nothing else.

#Referring to a contact or company

Paths take a :ref, one of:

URL-encode the ref (encodeURIComponent) when it can contain /, ?, # or %.

#Contacts

Contact (packages/sdk/src/types.ts):

{
  "id": "4f7c1f0e-…", "externalId": "KT00123", "email": "ola@firma.no",
  "firstName": "Ola", "lastName": "Nordmann", "phone": "+47 900 00 000", "title": "Innkjøpssjef",
  "language": "no", "companyId": "9a1b…", "attributes": { "segment": "industri" },
  "subscriptions": [{ "listId": "c2d4…", "status": "subscribed", "basis": "legitimate_interest", "updatedAt": "…" }],
  "suppressed": null, "createdAt": "…", "updatedAt": "…"
}

Input fields (all optional, but a new contact needs email or externalId): externalId, email, firstName, lastName, phone, title, language, companyId or companyExternalId (null unlinks), attributes. A field left out is kept, null clears it, attributes are merged (null removes a key).

Syncing. Pull changes with GET /server/contacts?updatedSince=<last run> and follow nextCursor until it is null. Push changes with POST /server/contacts/bulk, using your own id as externalId so a changed e-mail address updates the right contact.

Activities from your systems. type is your own name (order.created, quote.sent, meeting.held: lower case, digits, ., -, _, ≤ 60 chars), title a line for people, data any JSON up to 8 kB. Send your own id as externalId and a retried push is stored once. Activities you log have source: "api"; Snakkbar's own have source: "snakkbar".

#Companies

Company: id, externalId, name, domain (lower case, no www.), orgNumber, attributes, createdAt, updatedAt.

Contacts of a company: GET /server/contacts?companyId=<id>.

#Lists

ContactList: id, name, description, public (shown on the subscriber's preference page), doubleOptIn (sign-ups from forms wait for a confirmation mail), subscribed (count), createdAt, archivedAt.

#Suppressions

#Webhooks

Subscribe to contact.subscribed, contact.unsubscribed and contact.deleted (webhooks.md) to mirror subscription changes into your own systems, for example to mark a contact as "no marketing" in your ERP when they unsubscribe from a mail. Subscription events carry the contact as it is now (contact). Changes your own key made are included, so apply them idempotently. Plain field changes made through the API fire no events: your system made them and already knows.

#Limits