README

Laravel package for MX18 Email API integration. Send single/bulk emails and handle webhooks with ease.

Version 2.1.0 - New Feature

🚀 New Features:

✅ addRecipient() method for efficient bulk emails
✅ Multiple recipients with individual personalization in single API call

Version 2.0.0 - Major Release

🚀 New Features:

✅ Custom headers support
✅ Custom arguments for tracking
✅ Full MX18 API v1 compatibility

⚠️ Breaking Changes:

Authentication changed from Bearer token to X-Api-Key header
See Migration Guide below

Features

✅ Send single emails
✅ Send bulk emails
✅ Handle webhooks with signature verification
✅ Support for HTML/text content
✅ File attachments
✅ Email personalization
✅ CC/BCC recipients
✅ Custom headers
✅ Custom arguments
✅ Laravel auto-discovery

Requirements

PHP 8.3+
Laravel 10.0+, 11.0+, or 12.0+
MX18 account with API token

Installation

composer require ankitfromindia/mx18-laravel

Configuration

1. Publish Config

php artisan vendor:publish --tag=mx18-config

2. Environment Variables

Add to your .env:

MX18_API_TOKEN=your_api_token_here
MX18_WEBHOOK_SECRET=your_webhook_secret_optional
MX18_WEBHOOK_PATH=/mx18/webhook

3. Get API Token

Sign up at MX18
Get your API token from Account Settings
Verify your sender domain

Usage

Basic Email

use AnkitFromIndia\MX18\Mail\MX18Mail;
use AnkitFromIndia\MX18\Facades\MX18;

$mail = (new MX18Mail())
    ->from('sender@yourdomain.com', 'Your Name')
    ->to('recipient@example.com', 'Recipient Name')
    ->subject('Welcome to Our Service')
    ->html('<h1>Hello {{name}}!</h1><p>Welcome to our platform.</p>')
    ->text('Hello {{name}}! Welcome to our platform.');

$response = MX18::send($mail);

Advanced Email with Personalization

$mail = (new MX18Mail())
    ->from('noreply@yourdomain.com', 'Your Company')
    ->to('user@example.com', 'John Doe', ['name' => 'John', 'plan' => 'Premium'])
    ->cc('manager@yourdomain.com', 'Manager')
    ->replyTo('support@yourdomain.com', 'Support Team')
    ->subject('Your {{plan}} account is ready!')
    ->html('<h1>Hi {{name}}</h1><p>Your {{plan}} plan is now active.</p>')
    ->globalPersonalization(['company' => 'Your Company']);

$response = MX18::send($mail);

File Attachments

$pdfContent = base64_encode(file_get_contents('/path/to/file.pdf'));

$mail = (new MX18Mail())
    ->from('sender@yourdomain.com')
    ->to('recipient@example.com')
    ->subject('Invoice Attached')
    ->html('<p>Please find your invoice attached.</p>')
    ->attach($pdfContent, 'invoice.pdf', 'application/pdf');

$response = MX18::send($mail);

Custom Headers and Arguments

$mail = (new MX18Mail())
    ->from('sender@yourdomain.com')
    ->to('recipient@example.com')
    ->subject('Email with Custom Headers')
    ->html('<p>Email content</p>')
    ->headers([
        'X-Custom-Header' => 'CustomValue',
        'X-Mailer' => 'MX18 API'
    ])
    ->customArguments([
        'customerAccountNumber' => '12345',
        'campaignId' => 'summer2024'
    ]);

$response = MX18::send($mail);

Efficient Bulk Email (New in v2.1.0)

$mail = (new MX18Mail())
    ->from('newsletter@yourdomain.com', 'Your Company')
    ->addRecipient('user1@example.com', 'John', ['name' => 'John', 'plan' => 'Premium'])
    ->addRecipient('user2@example.com', 'Jane', ['name' => 'Jane', 'plan' => 'Basic'])
    ->subject('Welcome {{name}}!')
    ->html('<h1>Hi {{name}}</h1><p>Your {{plan}} plan is ready.</p>');

$response = MX18::send($mail);

Bulk Email

$mails = [
    (new MX18Mail())
        ->from('newsletter@yourdomain.com')
        ->to('user1@example.com', 'User One')
        ->subject('Newsletter #1')
        ->html('<h1>Newsletter Content</h1>'),
    
    (new MX18Mail())
        ->from('newsletter@yourdomain.com')
        ->to('user2@example.com', 'User Two')
        ->subject('Newsletter #2')
        ->html('<h1>Different Content</h1>'),
];

$responses = MX18::sendBulk($mails);

foreach ($responses as $response) {
    echo "Transaction ID: " . $response['transactionId'] . "\n";
}

Webhooks

1. Setup Webhook URL

Get your webhook URL:

$webhookUrl = MX18::getWebhookUrl();
// Returns: https://yourdomain.com/mx18/webhook

Configure this URL in your MX18 Dashboard under Webhooks settings.

2. Handle Webhook Events

Create an event listener:

// In EventServiceProvider.php
use AnkitFromIndia\MX18\Webhooks\WebhookReceived;

protected $listen = [
    WebhookReceived::class => [
        'App\Listeners\HandleMX18Webhook',
    ],
];

Create the listener:

// app/Listeners/HandleMX18Webhook.php
<?php

namespace App\Listeners;

use AnkitFromIndia\MX18\Webhooks\WebhookReceived;

class HandleMX18Webhook
{
    public function handle(WebhookReceived $event)
    {
        $payload = $event->payload;
        
        // Handle different event types
        switch ($payload['event']) {
            case 'delivered':
                // Email was delivered
                break;
            case 'opened':
                // Email was opened
                break;
            case 'clicked':
                // Link was clicked
                break;
            case 'bounced':
                // Email bounced
                break;
        }
    }
}

3. Webhook Security

The package automatically verifies webhook signatures when MX18_WEBHOOK_SECRET is set. Invalid signatures return 401 Unauthorized.

API Response

Successful API calls return:

[
    'transactionId' => 'abc123xyz456',
    'status' => 'Accepted',
    'message' => 'Email request has been accepted for delivery.'
]

Error Handling

try {
    $response = MX18::send($mail);
    echo "Email sent! Transaction ID: " . $response['transactionId'];
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Configuration Options

// config/mx18.php
return [
    'api_token' => env('MX18_API_TOKEN'),
    'api_url' => env('MX18_API_URL', 'https://api.mx18.com/api/1'),
    'webhook_secret' => env('MX18_WEBHOOK_SECRET'),
    'webhook_path' => env('MX18_WEBHOOK_PATH', '/mx18/webhook'),
];

Testing

composer test

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Security

If you discover any security vulnerabilities, please email security@ankitfromindia.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

Migration from v1.x

Breaking Changes in v2.0.0

The authentication method has changed to match the official MX18 API specification:

Before (v1.x):

// Used Authorization: Bearer header (incorrect)

After (v2.0.0):

// Now uses X-Api-Key header (correct)
// No code changes needed - just update your package version

New Features Available

// Custom headers
$mail->headers([
    'X-Campaign-ID' => 'summer2024',
    'X-Mailer' => 'My App'
]);

// Custom arguments for tracking
$mail->customArguments([
    'userId' => '12345',
    'source' => 'newsletter'
]);

Your existing code will continue to work without changes. Only the internal authentication method has been updated.

ankitfromindia / mx18-laravel

Maintainers

Details