Status Reasons

Possible values for reason field in subscription webhooks.

Unsubscribe reasons

Reason	Description
unsubscribed_by_user	User clicked unsubscribe link in email
unsubscribed_by_admin	Admin unsubscribed in Mission Control
unsubscribed_via_api	Unsubscribed via Trace API
bounced_hard	Email address hard bounced
bounced_soft	Email address soft bounced (multiple times)
complained	User marked email as spam

Subscribe reasons

Reason	Description
subscribed_via_form	Subscribed through website form
subscribed_via_api	Subscribed via Trace API
subscribed_via_import	Subscribed through data import
resubscribed	Previously unsubscribed, now resubscribed

Handling reasons

def handle_subscription_change(email, status, reason):
    if reason == 'bounced_hard':
        # Mark email as invalid in your system
        mark_email_invalid(email)

    elif reason == 'complained':
        # User marked as spam - handle carefully
        log_spam_complaint(email)

    elif reason == 'unsubscribed_by_user':
        # Normal unsubscribe
        update_preferences(email, subscribed=False)

Best practices

1. Hard bounces - Remove from mailing lists permanently
2. Spam complaints - Investigate and improve email practices
3. Soft bounces - May recover, keep monitoring
4. User unsubscribes - Respect immediately