Consent sync

Consent is per contact, per channel, per message type. A contact can have newsletter consent for email, no consent for RCS newsletter, and full consent for SMS — all independently. This guide walks through setting up a compliant, auditable consent flow from first opt-in to ongoing sync.

You do not need to complete every step before sending. Start with Step 1 (understand the model) and Step 2 (import existing consent) — these unblock your first send. Steps 3–5 build toward continuous, automated compliance.

Understand the consent model

Before importing or syncing anything, understand how consent is stored and enforced. The full consent model — field reference, DOI lifecycle, example payloads, and enforcement rules — is documented in Contacts — Consent model. Here’s the summary you need for this guide:

Consent is structured, not a boolean flag. Each contact holds a consent_records[] array — one entry per channel_type + message_type combination (EMAIL/RCS/SMS × MESSAGE/NEWSLETTER).
Status values: GRANTED (sends permitted), REVOKED (blocked), PENDING (DOI awaiting confirmation).
Enforcement: Sends without a GRANTED record for the matching combination return 422. Opt-out events set the record to REVOKED immediately.
DOI: When enforced_doi: true, status stays PENDING until the contact confirms via the doi_channel. Only then does it advance to GRANTED.

Action-based (MESSAGE) sends do not require subscription consent — they’re for receipts, alerts, and verification flows. NEWSLETTER sends always require an explicit GRANTED consent record. Do not use MESSAGE to bypass consent requirements for promotional content.

Import existing consent from your list

If you’re migrating from another platform or ESP, your current opt-in list is the starting point. The import must carry consent evidence — not just a list of addresses.What to prepare in your CSV:

Column	Notes
`email`	Primary deduplication key
`phone`	international format (e.g. `+4930123456`) for RCS/SMS
`first_name`, `last_name`	Contact identity
`email_newsletter_consent`	`true` / `false`
`rcs_newsletter_consent`	`true` / `false` (if applicable)
`consent_date`	ISO 8601 — used as `granted_at`
`consent_source`	Free text — stored as `source` in the record

Import flow:

Go to Contacts → Import and upload the CSV.
Map each column to the corresponding contact or consent field.
Apply a tag (e.g. migrated-2026-q1) so you can segment and audit this batch.
Contacts without a consent_date will have granted_at set to the import timestamp — note this in your records.

Only import contacts for whom you hold a valid prior opt-in record under GDPR, CAN-SPAM, or the applicable regulation in your market. The platform stores what you provide — it cannot validate the legality of consent collected before import.

Capture new consent with landing pages (coming soon)

Platform landing pages are coming soon. The flow below describes the planned behaviour. For now, capture opt-ins on your own forms and write consent via the API sync approach in Step 4.

When landing pages launch, net-new opt-ins will work like this:

Build the page — add a form block with name, email, phone, and a consent checkbox with explicit opt-in language.
Enable double opt-in (DOI) — the platform creates a consent record with status: PENDING, enforced_doi: true, and doi_status: DOI_SEND, then dispatches a confirmation email.
Contact confirms — when the contact clicks the confirmation link, the platform updates status to GRANTED and doi_status to DOI_ACCEPTED. granted_at is stamped at this moment.
Consent records will include proof_text with the landing page URL, an ip_hash, and the full DOI audit trail.

Keep consent in sync with your integrations

As your contact base grows, consent changes happen in Shopify, your unsubscribe flow, and your forms — all of which need to stay in sync with the platform.

Shopify (coming soon)
API sync (available now)
Webhooks write-back

Shopify integration is on the roadmap. When available, it will connect via OAuth under Contacts → Integrations and sync marketing email consent in real time via Shopify webhooks, including write-back for unsubscribes. Until then, use the API sync approach below.

For custom integrations or any data source, manage consent via the dedicated Consent API:

# Grant subscription consent (single opt-in)
curl -X POST "https://api.arowana.app/v1/contacts/c_a1b2c3d4/consent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "EMAIL",
    "message_type": "NEWSLETTER",
    "status": "GRANTED",
    "source": "crm_sync",
    "proof_text": "Marketing opt-in confirmed in HubSpot CRM on 2026-03-01"
  }'

# Revoke consent (opt-out)
curl -X DELETE \
  "https://api.arowana.app/v1/contacts/c_a1b2c3d4/consent/cr_a1b2c3" \
  -H "Authorization: Bearer $API_KEY"

Each POST is a targeted upsert for one channel_type + message_type pair — other consent records are not affected. Revocation preserves the full audit trail: status becomes REVOKED and revoked_at is stamped.

When a contact unsubscribes via an email one-click link or an RCS STOP reply, the platform emits an email.unsubscribed webhook event and updates the contact’s consent record immediately.Set up a webhook handler to receive this event and update the corresponding record in your system of record, preventing re-import of opted-out contacts on the next sync:

{
  "id": "evt_x1y2z3",
  "event": "email.unsubscribed",
  "timestamp": "2026-03-28T14:00:00Z",
  "data": {
    "contact_id": "c_a1b2c3d4",
    "channel_type": "EMAIL",
    "message_type": "NEWSLETTER",
    "consent_record_id": "cr_a1b2c3",
    "reason": "one_click_unsubscribe"
  }
}

See the Event types catalogue for all available webhook events.

Manage opt-outs and suppression

Opt-outs happen continuously. The platform handles the mechanics automatically — your job is to ensure nothing re-imports suppressed contacts.What happens automatically:

Email unsubscribe (one-click or link): email.unsubscribed event emitted; consent record updated; MANUAL_UNSUBSCRIBE suppression applied
Hard email bounce: email.bounced with bounce_type: hard; HARD_BOUNCE suppression applied; no future sends
Email complaint: email.complained event emitted; COMPLAINT suppression applied
RCS STOP reply: RCS newsletter consent revoked
SMS STOP: SMS consent revoked

What you need to manage:

Prevent re-import: Before any CSV import, look up the contact via GET /v1/contacts/{id} and check their status field — contacts with BOUNCED or BLOCKED status are skipped by the import tool automatically.
Integration write-back: Handle the email.unsubscribed webhook to update your Shopify or CRM record — prevents suppressed contacts from being re-added on the next sync.
Audit regularly: Export the consent audit log from Contacts → Compliance to verify that consent records match your source of truth.

Suppression is channel and message type specific. A hard bounce on email subscription sends does not automatically suppress email action-based sends — action-based mail (receipts, alerts) may still be deliverable to the same address.

Webhooks

email.unsubscribed, email.bounced, and email.complained event payloads.

Contacts

Full contact record shape and consent model.

Compliance checklist

Before your first newsletter send

Ongoing

Shopify (or other integration) sync uses POST /v1/contacts/{id}/consent for opt-in and DELETE for opt-out — not a bulk PATCH
Webhook handler for email.unsubscribed calls DELETE /v1/contacts/{id}/consent/{record_id} and writes back to your data source
CSV imports use the dashboard import tool (it checks suppression state and skips blocked contacts automatically)
Consent audit log (GET /v1/contacts/{id}/consent) is reviewed at least monthly
RCS STOP replies are handled (automatic — verify doi_status and revoked_at in contact consent records)

Landing pages

Opt-in forms, DOI, and consent capture at scale.

Contacts

Contact structure, PII encryption, and consent model.

Webhooks

Unsubscribe, bounce, and complaint event payloads.

Email campaign path

Put consent to work in your first email newsletter.

Your first multi-channel campaign

RCS → SMS fallback

Start here

Quickstarts

Learning paths

Learn

Concepts

Platform

Webhooks

Contacts

Compliance checklist

Landing pages

Contacts

Webhooks

Email campaign path

Start here

Quickstarts

Learning paths

Learn

Concepts

Platform

Webhooks

Contacts

​Compliance checklist

​Related

Landing pages

Contacts

Webhooks

Email campaign path

Compliance checklist

Related