fullstack / inbounder
A comprehensive Laravel package for Mailgun integration with email templates, distribution lists, webhook handling, and queue management.
Requires
- php: ^8.2
- laravel/framework: ^10.0|^11.0|^12.0
- spatie/laravel-permission: ^6.0
- symfony/http-client: ^6.0|^7.0
- symfony/mailgun-mailer: ^6.0|^7.0
Requires (Dev)
- fakerphp/faker: ^1.23
- laravel/pint: ^1.22
- mockery/mockery: ^1.6
- nunomaduro/collision: ^7.0|^8.0
- orchestra/testbench: ^8.0|^9.0|^10.0
- pestphp/pest: ^2.0|^3.0
- pestphp/pest-plugin-laravel: ^2.0|^3.0
- phpunit/phpunit: ^10.0|^11.0
- dev-main
- v0.3.55
- v0.3.54
- v0.3.53
- v0.3.52
- v0.3.51
- v0.3.50
- v0.3.49
- v0.3.48
- v0.3.47
- v0.3.46
- v0.3.45
- v0.3.44
- v0.3.43
- v0.3.42
- v0.3.41
- v0.3.40
- v0.3.39
- v0.3.38
- v0.3.37
- v0.3.36
- v0.3.35
- v0.3.34
- v0.3.33
- v0.3.32
- v0.3.31
- v0.3.30
- v0.3.29
- v0.3.28
- v0.3.27
- v0.3.26
- v0.3.25
- v0.3.24
- v0.3.23
- v0.3.22
- v0.3.21
- v0.3.20
- v0.3.19
- v0.3.18
- v0.3.17
- v0.3.16
- v0.3.15
- v0.3.14
- v0.3.13
- v0.3.12
- v0.3.11
- v0.3.10
- v0.3.9
- v0.3.8
- v0.3.7
- v0.3.6
- v0.3.5
- v0.3.4
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.6
- v0.2.5
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
This package is auto-updated.
Last update: 2025-07-02 04:13:09 UTC
README
A comprehensive Laravel package for Mailgun integration with email templates, distribution lists, webhook handling, and queue management.
Features
- Email Templates: Create and manage reusable email templates with variable substitution
- Distribution Lists: Manage email distribution lists with subscriber management
- Webhook Processing: Handle Mailgun webhooks for tracking and analytics
- Inbound Email: Process incoming emails with attachment support
- Queue Management: Dedicated queue configuration for email processing
- Authorization: Flexible authorization system (Gates, Policies, Spatie Permissions)
- Event System: Comprehensive event system for all operations
- Console Commands: CLI tools for managing templates and distribution lists
Installation
composer require fullstack/inbounder
Configuration
Basic Configuration
Publish the configuration file:
php artisan vendor:publish --tag=inbounder-config
Configure your Mailgun credentials in .env
:
MAILGUN_DOMAIN=your-domain.com MAILGUN_SECRET=your-api-key MAILGUN_WEBHOOK_SIGNING_KEY=your-webhook-signing-key MAIL_FROM_ADDRESS=noreply@your-domain.com MAIL_FROM_NAME=Your App Name
Queue Configuration
The package supports custom queue configuration for better performance and isolation:
# Enable custom queue configuration MAILGUN_QUEUE_ENABLED=true # Default queue name MAILGUN_QUEUE_NAME=mailgun # Specific queue names for different job types MAILGUN_QUEUE_TEMPLATED_EMAILS=mailgun-emails MAILGUN_QUEUE_WEBHOOKS=mailgun-webhooks MAILGUN_QUEUE_INBOUND=mailgun-inbound MAILGUN_QUEUE_TRACKING=mailgun-tracking # Queue connection (default, redis, sqs, etc.) MAILGUN_QUEUE_CONNECTION=redis # Retry configuration MAILGUN_QUEUE_MAX_ATTEMPTS=3 MAILGUN_QUEUE_RETRY_DELAY=60 MAILGUN_QUEUE_BACKOFF=true # Timeout configuration MAILGUN_QUEUE_JOB_TIMEOUT=300 MAILGUN_QUEUE_TIMEOUT=600 # Batch processing MAILGUN_QUEUE_BATCH_ENABLED=true MAILGUN_QUEUE_BATCH_SIZE=100 MAILGUN_QUEUE_BATCH_DELAY=5
Queue Workers
Set up queue workers for the Mailgun queues:
# Process templated emails php artisan queue:work --queue=mailgun-emails # Process webhook events php artisan queue:work --queue=mailgun-webhooks # Process inbound emails php artisan queue:work --queue=mailgun-inbound # Process tracking events php artisan queue:work --queue=mailgun-tracking
Or use supervisor to manage multiple workers:
[program:mailgun-emails] command=php /path/to/your/app/artisan queue:work --queue=mailgun-emails --sleep=3 --tries=3 autostart=true autorestart=true user=www-data numprocs=2 redirect_stderr=true stdout_logfile=/path/to/your/app/storage/logs/mailgun-emails.log
Usage
Email Templates
Create an email template:
use Inbounder\Models\EmailTemplate; $template = EmailTemplate::create([ 'name' => 'Welcome Email', 'slug' => 'welcome-email', 'subject' => 'Welcome to {{company}}!', 'html_content' => '<h1>Welcome {{name}}!</h1><p>Thank you for joining {{company}}.</p>', 'text_content' => 'Welcome {{name}}! Thank you for joining {{company}}.', 'variables' => ['name', 'company'], 'is_active' => true, ]);
Send a templated email:
use Inbounder\Services\TemplatedEmailJobDispatcher; $dispatcher = app(TemplatedEmailJobDispatcher::class); // Send to one recipient $dispatcher->sendToOne( 'user@example.com', 'welcome-email', ['name' => 'John Doe', 'company' => 'Acme Corp'] ); // Send to multiple recipients $recipients = [ ['email' => 'user1@example.com', 'name' => 'John', 'company' => 'Acme'], ['email' => 'user2@example.com', 'name' => 'Jane', 'company' => 'Acme'], ]; $dispatcher->sendToMany($recipients, 'welcome-email'); // Send as a batch $batch = $dispatcher->sendBatch($recipients, 'welcome-email');
Distribution Lists
Create a distribution list:
use Inbounder\Models\DistributionList; $list = DistributionList::create([ 'name' => 'Newsletter Subscribers', 'slug' => 'newsletter-subscribers', 'description' => 'Monthly newsletter subscribers', 'category' => 'newsletter', 'is_active' => true, ]);
Add subscribers:
use Inbounder\Services\DistributionListService; $service = app(DistributionListService::class); $service->addSubscribers($list->id, [ ['email' => 'user1@example.com', 'name' => 'John Doe'], ['email' => 'user2@example.com', 'name' => 'Jane Smith'], ]);
Send to distribution list:
$service->sendCampaign($list->id, 'newsletter-template', [ 'month' => 'January', 'year' => '2024', ]);
Webhook Handling
Set up webhook routes in your routes/web.php
:
Route::post('/mailgun/webhook', [MailgunController::class, 'webhook']) ->middleware('verify.mailgun.webhook'); Route::post('/mailgun/inbound', [MailgunController::class, 'inbound']) ->middleware('verify.mailgun.webhook');
Authorization
Configure authorization in your config/inbounder.php
:
'authorization' => [ 'method' => 'gate', // 'gate', 'policy', or 'spatie' 'gate_name' => 'send-email', 'policy_method' => 'sendEmail', 'spatie_permission' => 'send email', ],
Define your authorization logic:
// Using Gates Gate::define('send-email', function ($user) { return $user->hasPermission('send-email'); }); // Using Policies class UserPolicy { public function sendEmail(User $user): bool { return $user->hasPermission('send-email'); } } // Using Spatie Permissions $user->givePermissionTo('send email');
Events
Listen to package events:
use Inbounder\Events\EmailTemplateCreated; use Inbounder\Events\DistributionListCreated; Event::listen(EmailTemplateCreated::class, function ($event) { Log::info('Email template created', [ 'template_id' => $event->getTemplateId(), 'template_name' => $event->getTemplateName(), ]); }); Event::listen(DistributionListCreated::class, function ($event) { Log::info('Distribution list created', [ 'list_id' => $event->getListId(), 'list_name' => $event->getListName(), ]); });
Console Commands
Email Templates
# Create a template php artisan inbounder:templates:create # List templates php artisan inbounder:templates:list # Send a templated email php artisan inbounder:templates:send
Distribution Lists
# Create a distribution list php artisan inbounder:lists:create # List distribution lists php artisan inbounder:lists:list # Add subscribers php artisan inbounder:lists:add-subscribers # Remove subscribers php artisan inbounder:lists:remove-subscribers # Send campaign php artisan inbounder:lists:send-campaign
Testing
Run the test suite:
composer test
The package includes comprehensive tests with high coverage for all components.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
This package is open-sourced software licensed under the MIT license.