Marketing consent

Marketing email and SMS only go to contacts who said yes. Each contact carries its consent per channel in marketing_consent: a status (granted, pending or withdrawn), where it came from (source) and when it changed. Every change is kept in the contact's consent history as evidence: who or what made it, from which address, and on what basis.

Transactional email (receipts, order confirmations) never needs consent.

Where it comes fromSource in the history
A sign-up form (consent box ticked)signup_form, or signup_form_double_opt_in while it waits for the email confirmation
The confirmation link of a double opt-in emaildouble_opt_in
Granted by someone in your organisation, on a basismanual_existing_customer, manual_in_person, manual_import
Given in a connected system, e.g. at your web shop's checkout, recorded by an integrationconnected_system
The unsubscribe link in an emailunsubscribe_link (withdrawn)
An SMS reply STOP / STARTsms_inbound_stop / sms_inbound_start

For people who didn't come through a form, such as existing customers or someone who agreed in your shop, record the basis the consent rests on:

cURL
curl -X POST https://crm.codefab.dev/api/v1/records/{id}/consent:grant \
-H "X-API-Key: cfk_…" -H "Content-Type: application/json" \
-d '{"basis": "existing_customer"}'
basisUse it when
existing_customerThey bought from you, you email them about similar products, and they can opt out in every email
given_in_personThey told you in person, by phone or in writing
imported_with_consentThey come from a list where they agreed to your marketing
given_at_sourceThey agreed in another system of yours (e.g. ticked the newsletter box at checkout) and an integration records it. A key with only consent:write can record consent without being able to send anything

The basis, the user or API key, and the time go into the consent history. In the app it's Grant consent in the contact's Email panel.

Someone who unsubscribed or reported spam themselves can't be granted back by you (409 recipient_unsubscribed). Only they can opt in again, for example through one of your sign-up forms.

Many contacts at once

cURL
curl -X POST https://crm.codefab.dev/api/v1/consent:grantBulk \
-H "X-API-Key: cfk_…" -H "Content-Type: application/json" \
-d '{"basis": "existing_customer", "tagId": "9c1e3a5b-…"}'

Give one of tagId, segmentId or recordIds (up to 1,000; tags and segments up to 10,000). The answer says how many were granted, already had consent, opted out themselves, had their consent withdrawn (withdrawn: by someone at your organisation or through the API; all are left as they are) or have no address. A bulk grant never overrides a withdrawal; if one of them really gave consent again, grant it on their contact. In the app: Tags → Grant email consent…. For a bigger list, import it with its consent column.

An integration, an import or the assistant can also write marketing_consent directly. The same rules apply: granted needs a source, the basis such as checkout (400 consent_source_required without one). It is refused for someone who opted out themselves (409 consent_withdrawn_by_person). Sending the record back with its consent unchanged is fine.

Withdraw, or ask them to confirm

  • POST /api/v1/records/{id}/consent:withdraw stops marketing email to the contact (receipts still go).
  • POST /api/v1/records/{id}/consent:request emails them a link to confirm (double opt-in); their consent is pending until they click it.

Sign-up forms have their own double opt-in setting; there is no organisation-wide one.

The pages and the email your contacts see

The unsubscribe page, the SMS opt-out page, the email asking someone to confirm their subscription and the page that thanks them use your email brand (colours, font, button), your organisation's name and these settings:

HTTP
PUT /api/v1/settings/contact-pages
{
"logoUrl": "https://cdn.example.se/logo.png",
"website": "https://www.example.se",
"texts": { "sv": { "unsubscribe.heading": "Vill du sluta få våra nyhetsbrev?" } }
}

Each is shown in the contact's language (locale): Swedish or English, or another language you wrote texts for, else your default language. A text you leave out uses the default wording; {{organisation}} is your name. Texts are plain text, and the buttons that unsubscribe or confirm are always there. GET lists the text keys and the defaults; POST …/contact-pages/preview draws a page (unsubscribe, unsubscribed, confirmed, sms_opt_out, sms_opted_out) or the email (opt_in_email) from unsaved settings.

SMS

SMS consent works the same way, with POST /api/v1/contacts/{id}/sms-consent and {"status": "granted"} or {"status": "withdrawn"}. A STOP reply can only be undone by the person (replying START).

Read the history

GET /api/v1/records/{id}/consent-history returns every change, newest first: channel, status, source, who made it, and for public forms and links the visitor's IP address and browser.