Skip to main content

Brevo Unsubscribe Webhook

Process unsubscribe requests from Brevo email campaigns to automatically revoke contact consents.

Endpoint​

POST /api/v1/brevo/unsubscribe

Authentication​

Requires bearer token authentication. See Authentication.

Request Format​

Headers​

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body​

At least one of email or phone must be provided.

{
  email?: string;
  phone?: string;
}

Response Format​

Success Response​

{
  "success": true,
  "message": "Unsubscribe processed successfully"
}

HTTP Status: 200 OK

Error Response​

{
  "error": "ValidationError",
  "message": "At least one of email or phone must be provided"
}

HTTP Status: 400 Bad Request

Behavior​

When an unsubscribe request is processed:

  1. The system searches for all form submissions matching the provided email or phone number
  2. General contact consent is revoked for all matching submissions
  3. The user will not receive future email or phone communications based on general contact consent

Important: This endpoint only revokes general contact consent. It does not affect:

  • Primary purpose consent
  • Event-specific consents
  • Other specialized consent types

Brevo Webhook Setup​

To automatically process unsubscribes from Brevo:

  1. Log in to your Brevo account
  2. Navigate to Settings → Webhooks
  3. Create a new webhook with:
    • URL: https://api.statelessapp.com/api/v1/brevo/unsubscribe
    • Events: Select "Unsubscribed"
    • Headers: Add Authorization: Bearer YOUR_API_KEY
  4. Save and test the webhook

Examples​

Unsubscribe by Email​

curl -X POST https://api.statelessapp.com/api/v1/brevo/unsubscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Unsubscribe by Phone​

curl -X POST https://api.statelessapp.com/api/v1/brevo/unsubscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567"
  }'

Unsubscribe by Both​

curl -X POST https://api.statelessapp.com/api/v1/brevo/unsubscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "phone": "+15551234567"
  }'

Use Cases​

  • Email Unsubscribes: Automatically process unsubscribe requests from Brevo campaigns
  • Phone Opt-Outs: Handle phone number opt-out requests
  • Multi-Channel Unsubscribes: Process unsubscribes across both email and phone channels
  • GDPR Compliance: Ensure immediate consent revocation in response to user requests

Notes​

  • Phone numbers should be in E.164 format (e.g., +15551234567)
  • The endpoint is idempotent - processing the same unsubscribe multiple times has no additional effect
  • Unsubscribe actions are logged for audit purposes
  • Processing is synchronous and completes before returning the response