README

Provides Directmail integration for Symfony Mailer - DirectKSA's internal mail relay service.

This transport allows Laravel applications to send emails through a centralized directmail service instead of directly to email providers like AWS SES, Mailgun, Postmark, etc.

Installation

1. Install the package:

   composer require directksa/directmail-mailer

2. Add DirectMail to your mail configuration:

   Option A: Automatic (Recommended)

   php artisan directmail:install

   Option B: Manual Add this to your config/mail.php file's mailers array:

   'mailers' => [
       'directmail' => [
           'transport' => 'directmail',
           'host' => env('DIRECTMAIL_HOST', 'directmail.directksa.com'),
           'app_key' => env('DIRECTMAIL_APP_KEY'),
           'app_secret' => env('DIRECTMAIL_APP_SECRET'),
       ],
       // ... your other mailers
   ],

3. Add your credentials to .env:

   MAIL_MAILER=directmail
   DIRECTMAIL_APP_KEY=your_app_key_here
   DIRECTMAIL_APP_SECRET=your_app_secret_here
   DIRECTMAIL_HOST=directmail.directksa.com

4. Start sending emails:

   Mail::to('user@example.com')->send(new YourMailable());

Note: Step 2 is required - the package needs to be configured in your mail.php file to work. You can either use the install command or add the configuration manually.

Environment Variables

Production

MAIL_MAILER=directmail
DIRECTMAIL_APP_KEY=your_app_key_here
DIRECTMAIL_APP_SECRET=your_app_secret_here
DIRECTMAIL_HOST=directmail.directksa.com

Local Development

MAIL_MAILER=directmail
DIRECTMAIL_APP_KEY=your_app_key_here
DIRECTMAIL_APP_SECRET=your_app_secret_here
DIRECTMAIL_HOST=directmail.test

The transport automatically detects:

• .test domains → HTTP (for local development)
• All other domains → HTTPS (for production)

Usage

Use Laravel's mail functionality as normal:

use Illuminate\Support\Facades\Mail;
use App\Mail\TestEmail;

Mail::to('user@example.com')->send(new TestEmail());

Authentication

The transport uses app_key:app_secret format in the Authorization header:

Authorization: Bearer app_key:app_secret

Features

• ✅ Surgical Installation - php artisan directmail:install adds config without touching anything else
• ✅ Zero Configuration - Just set environment variables and go
• ✅ Smart HTTPS/HTTP Detection - Uses .test domains for local development
• ✅ Ultra-minimal - Only 3-4 environment variables needed
• ✅ HTML and Text email support
• ✅ Attachments (base64 encoded)
• ✅ CC/BCC recipients
• ✅ Reply-To addresses
• ✅ Custom headers, tags, and metadata
• ✅ Error handling and logging
• ✅ Package Discovery - Auto-registers everything
• ❌ SMTP support (API only)