Download the PHP package mailvex/mailvex-php without Composer

Mailvex PHP & Laravel SDK

Official PHP & Laravel client library for Mailvex Email Infrastructure Engine.

Features

• 🚀 Full PHP & Laravel Support: Zero external dependencies (native ext-curl, ext-json), compatible with PHP 8.1 through 8.4+ and Laravel 9 through 13.
• 📎 Attachments: Attach files via local file path, raw binary/string data, or pre-encoded Base64.
• 👥 Multiple Recipients & Batch Dispatch:
  • Send to multiple recipients in a single send() call.
  • Send up to 500 individualized messages in a single sendBatch() call with per-recipient template variables and metadata.
• 🛡️ Webhook Signature Verification: HMAC-SHA256 signature verification (X-Mailvex-Signature: t=...,v1=...) with 5-minute replay tolerance, dual-key rotation overlap, and typed helper methods for bounce and complaint classifications.
• ✉️ Native Laravel Mail Transport: Fully integrates with Laravel's mail system (Mail::to()->send()), auto-converting attachments, headers, and metadata to Mailvex REST API payloads.
• ⚡ Resilient Delivery: Built-in exponential backoff retry and RFC 8058 One-Click Unsubscribe automation.

Installation

Install the package via Composer:

Standalone PHP Usage

1. Initialize Client

[!IMPORTANT] Base URL in Production: In development, baseUrl can default to http://localhost:8080. In production, leaving the base URL empty or pointing to localhost will throw an InvalidArgumentException.

2. Send Email with Attachments

Attach files from paths, raw data, or Base64 strings:

3. Send to Multiple Recipients in One Call

Provide an array of email addresses to to(), cc(), or bcc():

4. Send Batch Emails (Up to 500 Distinct Messages in One Call)

Use sendBatch() to dispatch distinct, personalized messages to multiple recipients in a single HTTP request:

Message Streams Guide

Mailvex organizes outbound traffic into Message Streams. Streams provide physical isolation between critical operational notifications and high-volume broadcast campaigns.

Stream Behavior & Guarantees

1. Queue Priority & Throughput Protection: transactional emails are dispatched to Priority 1 (mvx:delivery:p1), ensuring critical transactional emails are never delayed behind a 50,000-recipient newsletter blast.
2. Independent Suppression Lists: Suppression checks in Mailvex are scoped by (tenant_id, stream_id, address). If an applicant unsubscribes from marketing or broadcast updates, their address is only suppressed on the broadcast stream. Critical transactional messages (e.g. password resets, admission offers) will continue to deliver normally.
3. Automatic RFC 8058 Headers: When stream is broadcast, Mailvex automatically generates signed VERP tokens and embeds RFC 8058 List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers into the raw MIME message.

4. Setting Stream in Laravel:

   • MailvexTransport defaults to stream: transactional.

   • To send as broadcast via Laravel's native mailer, set the X-Mailvex-Stream header:

   • When using the Mailvex Facade or SDK directly:

Webhook Engine & Event Specifications

Mailvex delivers real-time HTTP POST notifications for delivery outcomes, recipient engagement, and reputation events.

Security & Signature Algorithm

Each delivery includes the header:

• Signature verification: v1 = HMAC-SHA256(secret, "$timestamp.$rawPayload").
• Clock drift defense: Verifies |current_time - t| <= 300 seconds (5-minute tolerance window).
• Dual-Key Rotation Overlap: When rotating secrets, Mailvex includes signatures for both current and previous secrets for 24 hours.
• De-duplication: The top-level id (evt_...) is unique per event and stable across retries. Use $event->getId() to de-duplicate events in your database. The header X-Mailvex-Delivery-Id (whd_...) identifies the individual transmission attempt.

Webhook Event Catalog

1. message.delivered

Fired when the destination MX server accepts the message with SMTP 250 2.0.0 OK.

2. message.bounced

Fired when delivery fails with an SMTP rejection code (5xx or terminal 4xx).

3. message.complained

Fired when a recipient reports the message as spam via an ISP Feedback Loop (ARF) or RFC 8058 one-click list unsubscribe.

Feedback Types ($event->getFeedbackType()): abuse, spam, fraud, misc. Mailvex automatically suppresses complained recipients.

4. message.opened & message.clicked

Fired when open-tracking pixel is requested or link redirection occurs (bot hits are filtered automatically).

• message.opened: {"message_id": "...", "recipient": "...", "ip": "198.51.100.x", "user_agent": "..."}
• message.clicked: {"message_id": "...", "recipient": "...", "url": "https://krea.edu.in/apply", "ip": "...", "user_agent": "..."}

Outbound Delivery Retry Policy

When receiving temporary errors (4xx / soft_bounce / rate_limited), Mailvex's delivery queue schedules retries using a 9-tier schedule with ±20% randomized jitter:

• Attempt 1: 1 minute
• Attempt 2: 5 minutes
• Attempt 3: 15 minutes
• Attempt 4: 30 minutes
• Attempt 5: 1 hour
• Attempt 6: 2 hours
• Attempt 7: 6 hours
• Attempt 8: 12 hours
• Attempt 9: 24 hours

Maximum delivery lifetime is 72 hours. If a soft bounce cannot be delivered after 9 attempts or 72 hours, its status transitions to failed and it is routed to the Dead Letter Queue (DLQ).

Laravel Integration (Laravel 9, 10, 11, 12, 13)

1. Configuration & Publishing

The package includes auto-discovery for MailvexServiceProvider and the Mailvex Facade.

Publish configuration:

Add your credentials to .env:

In config/mail.php:

2. Native Laravel Mailer with Attachments

3. Handling Webhooks in Laravel

Register the webhook route in routes/api.php:

Listen for Mailvex\Laravel\Events\WebhookReceived:

Testing

Run tests using PHP:

Or run PHPUnit:

License

The Mailvex PHP & Laravel SDK is open-source software licensed under the MIT license.