Marketing consents

This page is the API reference for developers reading or writing marketing consents.

The Marketing consents app decides who may receive advertising by email, SMS or WhatsApp, and on which legal basis, and it keeps the proof of it. A marketing send is allowed only to a confirmed subscription whose legal basis the subscription type allows. The eligibility route answers that per recipient, and the mailing and journey apps ask it before every batch. The app sends no advertising itself: its only mail is the transactional confirmation of a double opt-in.

Four rules hold on every route:

• Only a click confirms a double opt-in. The confirmation token is sent in the confirmation message and is never returned by any answer of this app. A type with requires_doi: false confirms at once on consent_single instead, with no click.
• Consent events are never edited or deleted. Only the IP-address truncation after retention and an erasure rewrite a row, and both keep its kind, legal basis and time.
• A withdrawal takes effect at once and is pushed to the sending service as a suppression for that subscription type. If the sending service did not receive the suppression, the lapse job retries it.
• A published consent text never changes. People agreed to exactly that wording.

Base path: /v1/marketing-consents.

Objects

Consent event kinds are requested, confirmation_sent, confirmed, withdrawn, lapsed, imported, basis_changed and erased. Legal bases are consent_doi (double opt-in), consent_single (a single opt-in, from an import or a type without double opt-in; a weaker proof), existing_customer (the narrow exception of §7 (3) UWG) and contract, which never allows advertising. The closed value sets are listed by GET /v1/marketing-consents/vocabularies.

Scopes

Every operation needs one capability key, marketing-consents.<resource>.<action>, shown next to it in the tables below. A key holds capability keys or a namespace such as marketing-consents.*, as the API keys page explains. A call that needs a scope the key does not hold is refused with 403.

The trash empty and purge routes are for the back office only: a call from a storefront contact is refused with 403 and purge_not_allowed. A storefront contact also cannot delete a row for good: its second DELETE is refused with 403 and not_permitted.

The market header

The app reads X-Revenexx-Market on a sign-up, on an import, on a preference link and on a preference save. The market is stored on the subscription or the preference link it creates. A sign-up without the header and without a market in its body has no market.

Trash and sync fields

Subscription types and consent texts go to the trash and carry deleted_at, deleted_by, deleted_by_id, trash_batch, purge_at and purge_blocked_reason; their lists take trashed. Subscription types and subscriptions (also the subscriptions inside a contact's consent record) carry the sync fields external_id, external_refs, source_data and source_synced_at. They are read-only here: no create or update body of these routes takes them. Consent texts have no sync fields. Shared rules: Trash; Sync fields.

Subscription types

• POST (create) body: required code (starts with a lowercase letter, then lowercase letters, digits and _) and labels. Optional: channels (default ["email"]), requires_doi (default true), allows_existing_customer (default false), similar_goods_note, descriptions, position.
• POST errors: 201 on success. 409 with code_taken, or in_trash when the code belongs to a type in the trash (restore that type instead). 422 with invalid_code, labels_required, invalid_channels or similar_goods_note_required (the existing-customer basis needs the similar goods named).
• PUT errors: 422 with code_immutable when the code changes, or the same validation codes as create. 409 with channel_in_use when a removed channel still holds subscriptions.
• DELETE errors: 409 with trash_blocked, and a blocker type_in_use when the type has subscriptions or published consent texts. Archive such a type instead.
• Archived types: a sign-up or an eligibility call names an archived type with 422 and subscription_type_archived.
• restore error: 409 with not_in_trash.

Consent texts

• POST (create) body: required subscription_type_id, locale (a language tag such as de or de-CH) and wording.
• POST errors: 201 on success. 422 with unknown_subscription_type, invalid_locale or wording_required. 409 with version_taken when another draft took the same version at the same moment.
• PUT errors: 409 with text_published for a published version. 422 with wording_required, or field_immutable when the body changes the type, the language or the version.
• DELETE errors: 409 with trash_blocked and a blocker text_published for a published version. A published version is proof and is never deleted.
• publish error: 409 with already_published.
• restore errors: 409 with not_in_trash, or parent_in_trash while the subscription type of the text is in the trash.

Vocabularies

Subscriptions

• request body: required subscription_type (the type's code). The address is email for the email channel, or phone for sms and whatsapp; address is an alias for whichever the channel takes. Optional: channel (default email, or sms when only phone is sent), contact_id, first_name, last_name, locale (default de), consent_text_id, source (form, storefront, admin or preference_centre; default storefront), source_ref, campaign_ref, market, page_url, ip and user_agent.
• request answers: 201 when the subscription is opened or reopened. 200 when nothing changed: the address is already confirmed, or a confirmation went out less than ten minutes ago.
• request errors: 422 with subscription_type_required (no code sent), unknown_subscription_type, subscription_type_archived, invalid_channel, channel_not_offered, address_required (no address sent), invalid_address, invalid_source (a source outside the four listed), no_consent_text (the type has no published text yet, so every sign-up is refused), unknown_consent_text (the consent_text_id belongs to another type) or consent_text_unpublished (the consent_text_id is still a draft).
• confirm body: none required. Optional ip, user_agent and page_url are written to the proof.
• confirm answers: 200 with the subscription's state, channel, its type as subscription_type with code and labels, and confirmed_at. A second click on a confirmed subscription answers 200 with already_confirmed: true and writes nothing.
• confirm errors: 404 with unknown_token when no pending sign-up answers to the token: it was never sent, withdrawn, erased or lapsed. 410 with confirmation_expired when the link has expired but the hourly lapse job has not yet lapsed the sign-up; that click lapses it. Once lapsed, the token answers 404 with unknown_token. Treat both as "sign up again".
• withdraw body: optional reason, stored as the event's source_ref. Withdrawing twice changes nothing.
• withdraw errors: 404 when no subscription has the id.
• eligibility body: required subscription_type (the code) and recipients (up to 500), each a plain address or { address, contact_id? }. Optional channel (default email).
• eligibility answers: a recipient is allowed only on a confirmed subscription. The refusal reasons are no_subscription, pending, lapsed, withdrawn, basis_not_allowed (the basis is not one the type allows), contract_basis (a contract never allows advertising) and erased.
• eligibility errors: 422 with subscription_type_required, unknown_subscription_type, subscription_type_archived, invalid_channel, channel_not_offered, recipients_required, or too_many_recipients (more than 500).
• preferences/links body: required recipients (up to 500), each a plain address or { address, contact_id? }. Optional channel (default email). 422 with recipients_required, too_many_recipients or invalid_channel.
• preferences/{token} body: choices, an array of { subscription_type, subscribed } items (the type's code and true or false), where subscribed: false withdraws at once and subscribed: true signs up (with a confirmation first when the type requires double opt-in). unsubscribe_all: true withdraws every type of the channel. Optional locale, ip and user_agent. Neither choices nor unsubscribe_all is 422 with choices_required.
• preferences/{token} errors: 404 with unknown_token when no link answers to the token, or its address was erased.

Evidence

Consent events

Contacts

Each contact route answers 422 with invalid_contact when contact_id is not a UUID.

Imports

• POST body: required subscription_type (the code), legal_basis and proof_note, and rows (up to 1000, each { address, first_name?, last_name?, consented_at?, source_ref? }). Optional channel (default email) and file_ref.
• POST basis: legal_basis is consent_single or existing_customer, never double opt-in, since the import did not see a click. The existing_customer basis needs a type that allows it.
• POST answers: 201 with the counts and the first 100 refused rows. A row is refused with a reason such as erased, withdrawn or already_subscribed.
• POST errors: 422 with import_basis_not_allowed (a basis other than the two above), basis_not_allowed (existing_customer on a type whose allows_existing_customer is off), proof_note_required, rows_required (an empty list), too_many_rows (more than 1000), unknown_subscription_type, subscription_type_archived, invalid_channel or channel_not_offered.
• proof_note is required: it says where the consent of these addresses is documented (system, period, form), because an import without it is a claim without proof.

Jobs

These three routes run the same work as the app's scheduled jobs, and they can be called by hand. Each call is bounded.

The doi_expiry_days setting (default 7) sets how long a confirmation link stays valid.

Errors on every route

Every route can also answer 401 (no valid credentials), 403 (the key lacks the scope), 404 for an unknown id, and 429 when the rate limit is reached. A delete answers 409 with trash_blocked when the row cannot go into the trash, and 409 with delete_blocked when a second delete cannot remove it for good yet. The blocker is named. A write to a row in the trash answers 409 with in_trash; restore it first.