README

A lightweight PHP client for sending email through the Avang Email HTTP API.

Requirements

PHP 7.2.5 or newer, including PHP 8.x
JSON extension
A MailerEver account
An Avang server URL and API key

Installation

Install the latest stable release with Composer:

composer require avangdev/avang-php-sendemail-api:^2.0

Then load Composer's autoloader:

<?php

require __DIR__ . '/vendor/autoload.php';

Send a message

Sign in to the MailerEver dashboard and copy the Route and API key for your server. The dashboard URL itself is not the API server URL.

<?php

require __DIR__ . '/vendor/autoload.php';

use AvangPhpApi\Base;
use AvangPhpApi\ComposeMessage;

$client = new Base(
    'https://app.mailerever.com', // Replace with the Route shown in your dashboard.
    'your-api-key'
);

$message = new ComposeMessage($client);
$message->to('john@example.com');
$message->to('mary@example.com');
$message->cc('manager@example.com');
$message->bcc('archive@example.com');
$message->from('Avang Example <sender@example.com>');
$message->sender('sender@example.com');
$message->replyTo('support@example.com');
$message->subject('Hello from Avang');
$message->tag('welcome-email');
$message->plainBody('Hello! This is the plain-text body.');
$message->htmlBody('<h1>Hello!</h1><p>This is the HTML body.</p>');
$message->header('X-Application', 'example-app');
$message->attach('hello.txt', 'text/plain', 'Hello from the attachment.');

$result = $message->send();

foreach ($result->recipients() as $email => $sentMessage) {
    echo $email . ': ' . $sentMessage->id() . PHP_EOL;
    echo 'Token: ' . $sentMessage->token() . PHP_EOL;
}

Calling to(), cc() or bcc() more than once adds multiple recipients. Attachment data is automatically Base64-encoded by the client.

Send a raw message

Use ComposeRawMessage when you already have a complete RFC 5322 message:

<?php

require __DIR__ . '/vendor/autoload.php';

use AvangPhpApi\Base;
use AvangPhpApi\ComposeRawMessage;

$client = new Base(
    'https://mailerever.net', // Replace with the Route shown in your dashboard.
    'your-api-key'
);
$message = new ComposeRawMessage($client);

$message->mailFrom('sender@example.com');
$message->rcptTo('recipient@example.com');
$message->data(
    "From: sender@example.com\r\n" .
    "To: recipient@example.com\r\n" .
    "Subject: Raw message example\r\n" .
    "Content-Type: text/plain; charset=UTF-8\r\n" .
    "\r\n" .
    "Hello from a raw message."
);

$result = $message->send();

foreach ($result->recipients() as $email => $sentMessage) {
    echo $email . ': ' . $sentMessage->id() . PHP_EOL;
}

Raw message data is automatically Base64-encoded before it is sent to the API.

Available message fields

Method	API field	Description
`to($address)`	`to`	Adds a primary recipient
`cc($address)`	`cc`	Adds a CC recipient
`bcc($address)`	`bcc`	Adds a BCC recipient
`from($address)`	`from`	Sets the From address
`sender($address)`	`sender`	Sets the envelope sender
`replyTo($address)`	`reply_to`	Sets the Reply-To address
`subject($subject)`	`subject`	Sets the subject
`tag($tag)`	`tag`	Sets an optional message tag
`plainBody($content)`	`plain_body`	Sets the plain-text body
`htmlBody($content)`	`html_body`	Sets the HTML body
`header($key, $value)`	`headers`	Adds a custom header
`attach($name, $contentType, $data)`	`attachments`	Adds an attachment

For raw messages, use mailFrom($address), rcptTo($address) and data($rawMessage).

Error handling

Network and HTTP errors are reported by Guzzle. Invalid JSON and API error responses throw RuntimeException:

<?php

use GuzzleHttp\Exception\GuzzleException;

try {
    $result = $message->send();
} catch (GuzzleException $exception) {
    // Connection or HTTP-level error.
    echo $exception->getMessage();
} catch (\RuntimeException $exception) {
    // Invalid response or an error returned by the API.
    echo $exception->getMessage();
}

Do not commit real API keys to your repository. Load credentials from environment variables or another secure configuration source.

Testing

Install development dependencies and run the test suite:

composer install
composer test

The tests use mocked API responses and do not send real email.

Upgrading from v1

Version 2 requires PHP 7.2.5 or newer and uses Guzzle 7. The message field names and the Avang API endpoints remain unchanged.

License

This package is open-source software licensed under the MIT license.

avangdev / avang-php-sendemail-api

Maintainers

Package info

Statistics

Security