Marketing SMS needs a consent record. A live
POST /v1/sms with class: "marketing" is refused with 403 consent_missing unless an unrevoked SMS consent exists for the number. Transactional SMS (OTPs, receipts, alerts) is never checked. Marketing email is governed by the unsubscribe link and the suppression list instead; you can record email consent too, and it is exported with the rest.Record consent
Create the contact and its consent in one call. The contact is matched on the email or the phone, so calling it again for the same person completes the record instead of duplicating it. Needs thecontacts:write scope.
POST /v1/contacts/{id}/consents records a further consent on an existing contact. Pick the source that describes how the person agreed; the evidence object is yours to fill and is shown back verbatim.
A fifth source,
attestation, is written by the dashboard: when a teammate sends a marketing SMS from the Send page they confirm that everyone on the list agreed or is a customer, and Sendbaze records that confirmation against each number that has no consent yet.
What the gate checks
Before a live marketing SMS is queued, Sendbaze looks the number up:- Opted out? A number that replied STOP (or was opted out on the Contacts page or with
POST /v1/contacts/{id}/opt-out) is refused with422 recipient_suppressed, whatever consents exist. Only the person can undo that: record a new consent with sourceformonce they opt back in, and the opt-out is cleared. - Consent on record? An unrevoked SMS consent for the number lets the send through. None means
403 consent_missing, withcontactsUrlpointing at the Contacts page. Nothing is queued or charged.
Opt-outs
A STOP reply to an SMS, or the unsubscribe link on a marketing email, does three things at once: the address or number is suppressed for marketing (transactional still sends), the contact is flagged as opted out on that channel, and every consent on that channel is revoked with the reason (stop_reply or unsubscribe). You get the sms.opted_out or email.unsubscribed webhook so your own records can follow.
Your own systems can do the same with POST /v1/contacts/{id}/opt-out and { "channel": "sms" }, and a teammate can on the Contacts page.
Prove it
Consent records are never deleted. Revoking setsrevokedAt and revokedReason; deleting a contact leaves its consents in place with contactId: null and the address or number as value. That is what a regulator asks for, and POPIA expects you to keep it for at least three years.
GET /v1/consents?value=%2B27821234567lists every record for one number, newest first, revoked ones included.GET /v1/consents/exportreturns the same as a CSV download, with the same filters (value,contactId,channel,active=true). The Contacts page has an Export consent CSV link for the whole organisation and one per contact.
captured_at), when it was stored (recorded_at), who recorded it, the revocation if any, and the evidence as JSON.
Contacts
A contact is the person behind the number or address:email, phone (E.164), attributes (your own flat fields such as first_name, for personalising sends) and the marketing status per channel.
On the dashboard, the Contacts page imports a spreadsheet (Excel or CSV) in bulk: pick the number and address columns, keep the other columns as fields, and say whether the list came with consent (recorded as source
import, with the file name and your note as evidence) or not. An import never clears an opt-out. Reads need read; writes need contacts:write. One email or phone belongs to one contact per organisation; if the email and the phone in a request belong to two different contacts the call answers 409 contact_conflict and nothing changes.