bayfrontmedia / mail-manager
Framework agnostic library to queue and send emails from multiple services using a consistent API.
Requires
- php: ^8.0
- ext-pdo: *
- bayfrontmedia/php-array-helpers: ^2.0
- phpmailer/phpmailer: ^6.9
- soundasleep/html2text: ^2.1
This package is auto-updated.
Last update: 2024-10-10 01:26:18 UTC
README
Framework agnostic library to queue and send emails from multiple services using a consistent API.
NOTE: Development is currently underway to integrate additional mail services (adapters) to Mail Manager, and these will be released as they are developed.
License
This project is open source and available under the MIT License.
Author
Requirements
- PHP
^8.0
PDO
PHP extension
Installation
composer require bayfrontmedia/mail-manager
Usage
NOTE: All exceptions thrown by Mail Manager extend Bayfront\MailManager\Exceptions\MailException
, so you can choose to catch exceptions as narrowly or broadly as you like.
Adapter
A Bayfront\MailManager\AdapterInterface
must be passed to both the Bayfront\MailManager\Mail
, and the Bayfront\MailManager\MailQueue
constructors.
There are a variety of adapters available, each with their own required configuration.
In addition, you may also create and use your own adapters to be used with Mail Manager.
All adapters have a getInstance()
method, which can be used to get the underlying instance used by the adapter.
PHPMailer
The PHPMailer adapter allows you to use PHPMailer for sending messages.
use Bayfront\MailManager\Adapters\PHPMailer;
$config = [
'smtp' => true,
'smtp_auth' => true,
'smtp_secure' => 'tls', // STARTTLS or SMTPS
'host' => 'mail.example.com',
'port' => 587,
'username' => 'your_name@example.com',
'password' => 'your_password',
'debug' => false
];
try {
$adapter = new PHPMailer($config);
} catch (AdapterException $e) {
die($e->getMessage());
}
The PHPMailer adapter also has a testConnection()
method you can use to test for a successful connection to the SMTP server.
Start using Mail Manager
You may choose one of the following classes to use:
The Bayfront\MailManager\Mail
class allows for the creation and immediate sending of messages.
No database is needed.
The Bayfront\MailManager\MailQueue
class is the same as above, only it requires a PDO
instance to work with queued messages.
Queued messages allow for messages to be sent programmatically at a later date.
Mail default configuration
use Bayfront\MailManager\Mail;
$mail = new Mail($adapter);
MailQueue default configuration
use Bayfront\MailManager\MailQueue;
use Bayfront\MailManager\Exceptions\QueueException;
$pdo = new PDO('mysql:host=example.com;dbname=database_name', 'username', 'password');
$queue_config = [
'table' => 'mail_queue', // Name of database table to use
'max_attempts' => 3 // Maximum number of failed sending attempts before deleting message
];
try {
$queue = new MailQueue($adapter, $pdo, $queue_config);
} catch (QueueException $e) {
die($e->getMessage());
}
Public methods
MailQueue only
create
Description:
Create a new message.
Parameters:
$message
(array)
Returns:
- (self)
Throws
Bayfront\MailManager\Exceptions\MessageException
Example:
$message = [
'to' => [ // Array of recipients
[
'address' => 'to@example.com'.
'name' => 'Recipient name' // Optional
]
],
'from' => [
'address' => 'you@example.com'
'name' => 'Your name' // Optional
],
'subject' => 'Message subject',
'body' => 'Message body'
];
try {
$mail->create($message);
} catch (MessageException $e) {
die($e->getMessage());
}
addAddress
Description:
Add a "To" recipient.
Parameters:
$address
(string)$name = NULL
(string|null): IfNULL
, a name will not be defined
Returns:
- (self)
Example:
$mail->addAddress('jane.doe@example.com', 'Jane Doe');
addCc
Description:
Add a "Cc" recipient.
Parameters:
$address
(string)$name = NULL
(string|null): IfNULL
, a name will not be defined
Returns:
- (self)
Example:
$mail->addCC('jane.doe@example.com', 'Jane Doe');
addBcc
Description:
Add a "Bcc" recipient.
Parameters:
$address
(string)$name = NULL
(string|null): IfNULL
, a name will not be defined
Returns:
- (self)
Example:
$mail->addBCC('jane.doe@example.com', 'Jane Doe');
addAttachment
Description:
Add an attachment.
Parameters:
$file
(string): Path to the file$name = NULL
(string|null): New name to assign to file. IfNULL
, the existing name will be used.
Returns:
- (self)
Example:
$mail->addAttachment('/path/to/existing/image.jpg', 'new-name.jpg');
discard
Description:
Discard message.
Parameters:
- None
Returns:
- (self)
Example:
$mail->discard();
send
Description:
Send message.
Parameters:
- None
Returns:
- (void)
Throws:
Bayfront\MailManager\MessageException
Example:
$mail->send();
addQueue
NOTE: This method is only available with the MailQueue
class.
Description:
Queue message.
Parameters:
$date_due
(\DateTimeInterface
)$priority = 5
(int): Messages will be sent in order by due date sorted by priority in descending order
Returns:
- (void)
Throws:
Bayfront\MailManager\QueueException
Example:
$message = [
'to' => [ // Array of recipients
[
'address' => 'to@example.com'.
'name' => 'Recipient name' // Optional
]
],
'from' => [
'address' => 'you@example.com'
'name' => 'Your name' // Optional
],
'subject' => 'Message subject',
'body' => 'Message body'
];
try {
$mail->create($message);
} catch (MessageException $e) {
die($e->getMessage());
}
try {
$mail->addQueue(new \Datetime('2020-10-01 10:35:00'));
} catch (QueueException $e) {
die($e->getMessage());
}
removeQueue
NOTE: This method is only available with the MailQueue
class.
Description:
Remove a given ID from the queue.
Parameters:
$id
(int): Uniqueid
from the database table
Returns:
- (bool)
Throws:
Bayfront\MailManager\QueueException
Example:
$mail->removeQueue(35);
getQueue
NOTE: This method is only available with the MailQueue
class.
Description:
Get all messages in queue that are due, up to a given limit.
Parameters:
$limit = 0
(int):0
to get all
Returns:
- (array)
Throws:
Bayfront\MailManager\QueueException
Example:
try {
print_r($mail->getQueue());
} catch (QueueException $e) {
die($e->getMessage());
}
sendQueue
NOTE: This method is only available with the MailQueue
class.
Description:
Send messages in queue that are due, up to a given limit.
Parameters:
$limit = 0
(int):0
to send all
Returns:
- (array)
Throws:
Bayfront\MailManager\QueueException
Example:
try {
$results = $mail->sendQueue(50); // Send up to 50 queued messages
} catch (QueueException $e) {
die($e->getMessage());
}
The returned array contains a result summary with the following structure:
[
'sent' => 0, // Number of messages sent
'removed' => 0, // Number of messages removed (exceeded max attempts)
'failed' => 0, // Number of messages failed
'failed_ids' => [] // Unique ID's of failed messages
];