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.
How consent arrives
| Where it comes from | Source 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 email | double_opt_in |
| Granted by someone in your organisation, on a basis | manual_existing_customer, manual_in_person, manual_import |
| Given in a connected system, e.g. at your web shop's checkout, recorded by an integration | connected_system |
| The unsubscribe link in an email | unsubscribe_link (withdrawn) |
| An SMS reply STOP / START | sms_inbound_stop / sms_inbound_start |
Grant email consent for a contact you added
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 -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"}'
basis | Use it when |
|---|---|
existing_customer | They bought from you, you email them about similar products, and they can opt out in every email |
given_in_person | They told you in person, by phone or in writing |
imported_with_consent | They come from a list where they agreed to your marketing |
given_at_source | They 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 -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.
Consent written as a field
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:withdrawstops marketing email to the contact (receipts still go).POST /api/v1/records/{id}/consent:requestemails them a link to confirm (double opt-in); their consent ispendinguntil 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:
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.