Unsubscribe Groups

Unsubscribe groups let recipients opt out of specific categories of email without unsubscribing from all your messages. For example, a recipient can unsubscribe from your marketing newsletter but still receive transactional receipts.

How it works

Create a group — each group represents a category of email (e.g., “Marketing”, “Product Updates”, “Billing”)
Send with a group — include group_id in your send request
Recipients unsubscribe — clicking the unsubscribe link in the email immediately opts the recipient out of the group associated with that message, then shows a generic confirmation page
Suppression is automatic — future sends to that recipient with the same group are blocked

Create an unsubscribe group

curl

curl -X POST https://api.telnyx.com/v2/email_unsubscribe_groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Marketing Newsletter",
    "description": "Weekly product updates and promotions"
  }'

Send with a group

Include the group_id field when sending a message to associate it with an unsubscribe group:

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": {"email": "marketing@yourdomain.com"},
    "to": [{"email": "user@example.com"}],
    "subject": "Weekly product roundup",
    "html_body": "<p>Here is what is new this week...</p>",
    "group_id": "{group_id}"
  }'

When a recipient clicks the unsubscribe link, they are opted out of that specific group only. If group_id is omitted, the unsubscribe becomes global — the recipient is suppressed from all future sends.

List group suppressions

View which recipients have unsubscribed from a specific group:

curl

curl -X GET https://api.telnyx.com/v2/email_unsubscribe_groups/{id}/suppressions \
  -H "Authorization: Bearer YOUR_API_KEY"

Add a suppression manually

Add a single recipient to a group’s suppression list (e.g., via a support request):

curl

curl -X POST https://api.telnyx.com/v2/email_unsubscribe_groups/{id}/suppressions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"to": "user@example.com"}'

Remove a suppression

Remove a suppression to allow sending again:

curl

curl -X DELETE https://api.telnyx.com/v2/email_unsubscribe_groups/{id}/suppressions/{email} \
  -H "Authorization: Bearer YOUR_API_KEY"

Best practices

Use groups for every marketing send — transactional emails can use a group too, but recipients should rarely want to unsubscribe from those
Keep group names clear — group names are for your internal organization
Don’t create too many — 3-5 groups is typical; more creates unnecessary complexity
Monitor suppression counts — high unsubscribe rates signal content or frequency issues
Always include group_id for marketing — without it, unsubscribes become global and block all future sends to that recipient

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

Unsubscribe Groups

How it works

Create an unsubscribe group

Send with a group

List group suppressions

Add a suppression manually

Remove a suppression

Best practices

​How it works

​Create an unsubscribe group

​Send with a group

​List group suppressions

​Add a suppression manually

​Remove a suppression

​Best practices

How it works

Create an unsubscribe group

Send with a group

List group suppressions

Add a suppression manually

Remove a suppression

Best practices