143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
# Mail Bounce System Documentation
|
|
|
|
## Overview
|
|
|
|
This system provides universal email bounce handling that works with any SMTP server by automatically intercepting all outgoing emails, checking for suppressed recipients, and processing bounce notifications from a dedicated mailbox.
|
|
|
|
## Key Features
|
|
|
|
- **Universal Protection**: Automatically protects ALL mailables (newsletters, contact forms, notifications, etc.)
|
|
- **SMTP Server Agnostic**: Works with any SMTP server that supports Return-Path headers
|
|
- **Threshold-Based Suppression**: Conservative approach with configurable bounce thresholds
|
|
- **Multi-Profile Support**: Handles Users, Organizations, Banks, and Admins
|
|
- **Email Verification Management**: Resets verification status based on bounce patterns
|
|
- **Comprehensive Logging**: Tracks all bounce processing and suppression actions
|
|
|
|
## How It Works
|
|
|
|
1. **Outgoing Emails**: All emails automatically get Return-Path and tracking headers
|
|
2. **Bounce Collection**: Bounces are sent to a dedicated mailbox (e.g., bounces@yourdomain.org)
|
|
3. **Bounce Processing**: System reads the mailbox and categorizes bounces (hard/soft/unknown)
|
|
4. **Threshold Checking**: Only definitive hard bounces count toward suppression thresholds
|
|
5. **Automatic Protection**: Suppressed emails are blocked from all future mailings
|
|
|
|
## Configuration
|
|
|
|
Configure bounce thresholds in `config/timebank-cc.php` under `mailing.bounce_thresholds`:
|
|
- **verification_reset_threshold**: Hard bounces before email_verified_at is reset (default: 2)
|
|
- **suppression_threshold**: Hard bounces before email is suppressed (default: 3)
|
|
- **counting_window_days**: Time window for counting bounces (default: 30 days)
|
|
|
|
Configure automatic cleanup in `config/timebank-cc.php` under `mailing.bounce_thresholds.automatic_cleanup`:
|
|
- **day_of_week**: Day for cleanup (0=Sunday, 1=Monday, etc.) (default: 1)
|
|
- **time**: Time to run cleanup in 24-hour format (default: '03:00')
|
|
- **cleanup_days**: Days after which to delete soft bounces (default: 90)
|
|
- **cleanup_bounce_types**: Bounce types to cleanup, hard bounces are preserved (default: ['soft', 'unknown'])
|
|
|
|
Set bounce mailbox in `.env`:
|
|
- **BOUNCE_PROCESSING_ENABLED**: Enable/disable bounce processing (set to `false` on local/staging without IMAP)
|
|
- **MAIL_BOUNCE_ADDRESS**: Return-Path address for bounces
|
|
- **BOUNCE_MAILBOX**, **BOUNCE_HOST**, etc.: IMAP settings for bounce processing
|
|
|
|
## Artisan Commands
|
|
|
|
### Process Bounce Emails
|
|
```bash
|
|
# Test bounce processing (dry run)
|
|
php artisan mailings:process-bounces --dry-run
|
|
|
|
# Process bounces and delete from mailbox
|
|
php artisan mailings:process-bounces --delete
|
|
|
|
# Process with custom mailbox settings
|
|
php artisan mailings:process-bounces --mailbox=bounces@example.com --host=imap.example.com --username=bounces@example.com --password=secret --ssl --delete
|
|
```
|
|
|
|
### Manage Bounced Emails
|
|
```bash
|
|
# Show bounce statistics and threshold information
|
|
php artisan mailings:manage-bounces stats
|
|
|
|
# List all bounced emails
|
|
php artisan mailings:manage-bounces list
|
|
|
|
# Check bounce counts for specific email
|
|
php artisan mailings:manage-bounces check-thresholds --email=user@example.com
|
|
|
|
# Check all emails against thresholds
|
|
php artisan mailings:manage-bounces check-thresholds
|
|
|
|
# Manually suppress an email
|
|
php artisan mailings:manage-bounces suppress --email=problem@example.com
|
|
|
|
# Remove suppression from an email
|
|
php artisan mailings:manage-bounces unsuppress --email=fixed@example.com
|
|
|
|
# Clean up old soft bounces
|
|
php artisan mailings:manage-bounces cleanup --days=90
|
|
```
|
|
|
|
### Test Universal Bounce System
|
|
```bash
|
|
# Test with suppressed email (should be blocked)
|
|
php artisan test:universal-bounce --scenario=suppressed --email=test@example.com
|
|
|
|
# Test with normal email (should work)
|
|
php artisan test:universal-bounce --scenario=normal --email=test@example.com
|
|
|
|
# Test with mixed recipients
|
|
php artisan test:universal-bounce --scenario=mixed
|
|
|
|
# Test specific mailable types
|
|
php artisan test:universal-bounce --scenario=normal --mailable=contact
|
|
```
|
|
|
|
### Test Bounce Threshold System
|
|
```bash
|
|
# Test single bounce (no action)
|
|
php artisan test:bounce-system --scenario=single
|
|
|
|
# Test verification reset threshold (2 bounces)
|
|
php artisan test:bounce-system --scenario=threshold-verification
|
|
|
|
# Test suppression threshold (3 bounces)
|
|
php artisan test:bounce-system --scenario=threshold-suppression
|
|
|
|
# Test all scenarios
|
|
php artisan test:bounce-system --scenario=multiple
|
|
```
|
|
|
|
## Bounce Types
|
|
|
|
- **Hard Bounce**: Permanent failure (user unknown, invalid domain) - counts toward thresholds
|
|
- **Soft Bounce**: Temporary failure (mailbox full, server down) - recorded but ignored
|
|
- **Unknown**: Unclassified bounces - recorded but ignored
|
|
|
|
## Threshold Actions
|
|
|
|
- **1 Hard Bounce**: Recorded, no action taken
|
|
- **2 Hard Bounces**: email_verified_at set to null for all profiles with this email
|
|
- **3 Hard Bounces**: Email suppressed from all future mailings
|
|
|
|
## Automatic Scheduling
|
|
|
|
The system automatically schedules the following tasks in `app/Console/Kernel.php`:
|
|
|
|
**Bounce Processing**: Every hour (only when `BOUNCE_PROCESSING_ENABLED=true`)
|
|
```php
|
|
$schedule->command('mailings:process-bounces --delete')
|
|
->hourly()
|
|
->withoutOverlapping()
|
|
->when(fn() => config('app.bounce_processing_enabled', false));
|
|
```
|
|
|
|
**Note**: Set `BOUNCE_PROCESSING_ENABLED=false` in `.env` on local development and staging environments to prevent IMAP connection errors.
|
|
|
|
**Automatic Cleanup**: Configurable via `timebank-cc.php` config (default: Mondays at 3:00 AM)
|
|
- Cleans up soft bounces older than the configured days (default: 90 days)
|
|
- Preserves hard bounces for suppression decisions
|
|
- Schedule automatically updates based on config settings
|
|
|
|
## Logging
|
|
|
|
The system logs all bounce processing and suppression actions with "MAILING:" prefix in Laravel logs. Monitor logs to track system activity and troubleshoot issues. |