Skip to main content
The Opt-Outs API keeps Connectly’s suppression list in step with the consent records in your own system. Send the contacts you must not message and Connectly stops delivering to them; send the ones who opted back in and Connectly resumes. Both routes are symmetric and safe to repeat, so the same daily export can be sent every night without special handling for what changed since yesterday.

How it works

1

Export your consent changes

Produce the list of contacts to suppress and the list to re-enable. Repeats inside one list are fine — the same contact listed twice counts once.
2

Suppress

Call Add opt-outs with up to 10,000 contacts. Campaigns and messages skip them from that point on.
3

Re-enable

Call Remove opt-outs for contacts who consented again. By default this clears only the opt-outs this API recorded. When you have collected new consent, set consentConfirmed to also clear STOP replies and unsubscribe-button taps.
4

Reconcile

Each response reports what changed, what was already in that state, and which entries could not be read. Unreadable entries are dropped and counted rather than failing the whole batch.
By default, Remove only reverses what this API suppressed. A contact who replied STOP or tapped an unsubscribe button stays suppressed unless you set consentConfirmed to true. Set it only when you have collected new consent from every contact in the request. Connectly enables it for your business on request.Two kinds of opt-out are never cleared by this API:
  • WhatsApp’s own marketing setting. Only the contact can turn marketing messages back on, in WhatsApp. The response counts these under marketingOptOutCount.
  • A file upload in the Connectly dashboard. Remove it from the dashboard.
Contacts held by either stay suppressed, and messages to them are still blocked.
To keep your records in step as contacts opt out or back in, subscribe to the opt_status_update webhook. It sends one event per contact whenever an opt-out changes whether you can message them, including STOP replies and WhatsApp marketing settings.

Identifying a contact

Every entry names one contact through either field: client takes precedence when both are set. userId is read only when client is empty. These are the same identifier rules as Send Campaigns, so a system that already targets contacts for campaigns can suppress them without a second identifier mapping.
Opt-outs are recorded per channel. Both routes act on WhatsApp.

Endpoints

Add opt-outs

POST /v1/businesses/{businessId}/add/opt_outs — suppress up to 10,000 contacts.

Remove opt-outs

POST /v1/businesses/{businessId}/remove/opt_outs — re-enable contacts who consented again.