README

A comprehensive email marketing and messaging system for Laravel applications, designed specifically for the Humano ecosystem.

Features

• Email Campaigns: Create and manage email marketing campaigns
• Multiple Providers: Support for SMTP and generic email APIs (MailBaby, Mailgun, SendGrid, etc.)
• Message Templates: Integration with template system for rich HTML emails
• Contact Management: Target specific contact categories and statuses
• Tracking & Analytics: Open tracking, click tracking, and detailed statistics
• Team-based: Multi-tenant support with team isolation
• Rate Limiting: Configurable sending limits and delays between emails
• Unsubscribe Management: Automatic unsubscribe handling
• Campaign Controls: Start, pause, and monitor campaigns
• Test Sending: Send test emails before launching campaigns

Installation

Install the package via Composer:

composer require idoneo/humano-mailer

Publish and run the migrations:

php artisan vendor:publish --tag="humano-mailer-migrations"
php artisan migrate

Optionally, publish the config file:

php artisan vendor:publish --tag="humano-mailer-config"

Configuration

The package automatically registers the "Mailer" module in your application. Configure your email providers in the .env file:

SMTP Configuration (Default)

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls

Email API Configuration (MailBaby, Mailgun, etc.)

For external email service providers, use these simplified variables:

# Generic API configuration - works with any email service
MAIL_API_KEY=your-api-key-here
MAIL_API_DOMAIN=your-domain.com  # Optional, only if your provider needs it

# Examples:
# For MailBaby: MAIL_API_KEY=your-mailbaby-api-key
# For Mailgun: MAIL_API_KEY=your-mailgun-secret-key and MAIL_API_DOMAIN=your-domain.mailgun.org
# For SendGrid: MAIL_API_KEY=your-sendgrid-api-key

The package will automatically detect if you have an API key configured and enable API-based sending.

Usage

Creating Messages

Messages can be created through the web interface or programmatically:

use Idoneo\HumanoMailer\Models\Message;

$message = Message::create([
    'name' => 'Welcome Campaign',
    'type_id' => 1,
    'template_id' => 1,
    'text' => 'Welcome to our platform!',
    'status_id' => 1,
    'team_id' => auth()->user()->currentTeam->id,
]);

Starting Campaigns

Campaigns can be started through the web interface or API:

$message = Message::find(1);
$message->update([
    'status_id' => 1, // Active
    'started_at' => now(),
]);

Tracking

The package provides comprehensive tracking:

• Open Tracking: Tracks when emails are opened
• Click Tracking: Tracks link clicks within emails
• Delivery Status: Monitors delivery success/failure
• Unsubscribe Tracking: Handles unsubscribe requests

Models

Message

The main campaign model with relationships to:

• MessageType: Campaign type (newsletter, promotional, etc.)
• Category: Target contact category
• Template: Email template for HTML content
• MessageDelivery: Individual email deliveries

MessageDelivery

Individual email delivery records with:

• Delivery status tracking
• Provider-specific data
• Open/click timestamps
• Error handling

MessageType

Campaign types for categorizing messages.

Routes

The package registers the following routes:

• GET /message/list - List all messages
• GET /message/create - Create new message form
• GET /message/{id} - View message details
• POST /message/{id}/start - Start campaign
• POST /message/{id}/pause - Pause campaign
• POST /message/{id}/test - Send test email

Team Integration

The package is designed for multi-tenant applications:

• All models are scoped to teams automatically
• Email configuration can be team-specific
• Statistics and deliveries are isolated by team

Dependencies

• spatie/laravel-package-tools: Package development tools
• yajra/laravel-datatables-oracle: DataTables integration
• guzzlehttp/guzzle: HTTP client for API calls
• tijsverkoyen/css-to-inline-styles: Email CSS processing

License

This package is licensed under the GNU AGPLv3.

Support

For support and documentation, visit the Humano documentation or contact support@idoneo.es.