lucinda/mailing

Very light weight PHP API for email sending and digital signing covering most important parts of RFC-4021 & RFC-6376 specs

v3.0.1 2022-06-13 06:27 UTC

Requires

• php: ^8.1
• ext-fileinfo: *
• ext-mbstring: *
• ext-openssl: *

MIT

• Lucian Gabriel Popescu

• OOP
• mailing
• dkim
• dkim-signature
• dkim signature

README

Very lightweight PHP API covering most important parts of RFC-4021, the worldwide standard at this moment for email sending, along with RFC-6376 for digital signatures.

API requires PHP 8.1+ and comes with just four classes, all belonging to Lucinda\Mail namespace:

• Address: encapsulates an email address, composed by value of email and name of user associated with it
• DKIM: creates a DKIM-Signature header using on a heavily refactored version of php-mail-signature classes
• Exception: encapsulates any logical error that prevents email from being sent
• Message: encapsulates an email message

The entire logic of email message is encapsulated by class Message via following public methods:

Simple example:

$message = new \Lucinda\Mail\Message("test subject", "<p>Hello, <strong>world</strong>!</p>");
$message->setMessageID("example.com"); // recommended to prevent message being labeled as spam
$message->setDate(time()); // signals that message was written now
$message->setContentType("text/html", "UTF-8"); // recommended, unless message is ASCII plaintext
$message->addTo(new Address("[e-mail]")); // mandatory
$message->setReplyTo(new Address("[e-mail]", "John Doe")); // recommended if message can be replied to
$message->send();

__construct

This method constructs a mail message by following arguments:

addAttachment

Adds an attachment to message body based on argument:

Example:

$message->addAttachment("/foo/bar/baz.jpg");

setFrom

Sets address of message author as seen by recipients (see: from header) based on argument:

Usually calling this method is not necessary, unless developer wants a different from address from that default.

Example:

$message->setFrom(new \Lucinda\Mail\Address("[e-mail]", "Example.com Team"));

setSender

Sets address of message author as seen by destination mail server (see: from header) based on argument:

Should be same as from address, unless mail server is sending messages on behalf of someone else.

Example:

$message->setSender(new \Lucinda\Mail\Address("[e-mail]", "Example.com Team"));

setReplyTo

Sets address to send message replies to (see: Reply-To header) based on argument:

Should always be set IF we desire messages to be replied to.

Example:

$message->setReplyTo(new \Lucinda\Mail\Address("[e-mail]", "Example.com Team"));

addTo

Adds an address to send message to (see: To header) based on argument:

At least one address must always be set!

Example:

$message->addTo(new \Lucinda\Mail\Address("[e-mail]"));

addCC

Adds an address to send a copy of message to allowing others to notice (see: Cc header) based on argument:

Example:

$message->addCC(new \Lucinda\Mail\Address("[e-mail]"));

addBCC

Adds an address to send a copy of message to without others to notice (see: Bcc header):

Example:

$message->addBCC(new \Lucinda\Mail\Address("[e-mail]"));

setContentType

Sets message body's content type and character set by following arguments (see: Content-Type header):

Example:

$message->setContentType("text/html", "UTF-8");

setDate

Sets custom date message was sent at based on argument (see: Date header):

Usually it is not necessary to send this header unless you want to trick receiver(s) it originated at a different date.

Example:

$message->setDate(time()-1000);

setMessageID

Sets unique ID of message to send based on argument (see: Message-ID header):

It is strongly recommended to send this header in order to prevent having your message labeled as spam by recipient mail servers!

Example:

$message->setMessageID("example.com");

setSignature

Sets a digital signature of message to send based on arguments (see: DKIM-Signature header):

In order to prevent having your message labeled as spam by recipient mail servers, setting this header is strongly recommended! To get values for params above, follow this guide:

• Go to https://tools.socketlabs.com/dkim/generator
  • fill hostname, which will be value of $domainName above (eg: "example.com")
  • write a $dnsSelector "subdomain" (eg: "dkim")
  • hit on GENERATE button
• Create a DNS TXT record for $selector._domainkey.$domainName. where value is string shown under "Step 2: Create your public DNS record"
• Store private key shown under "Step 3: Save the private key to your SMTP server" section somewhere. This will become value of $rsaPrivateKey
• Since you generated a key without a password $rsaPassphrase will always be an empty ""
• Now finally you must choose list of header names to generate signature from (eg: ["From", "Message-ID", "Content-Type"]) using $signedHeaders. See: recommendations for what should be chosen!

The algorithm used in generating DKIM-Signature header has been taken from php-mail-signature and refactored completely because original was chaotic and poorly programmed. The end result was class DKIM!

Example:

$message->setSignature("-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----", "", "example.com", "dkim", [
    "From",
    "Reply-To",
    "Subject",
    "To"
]);

addCustomHeader

Adds a RFC-4021 header not covered by commands above using following arguments:

Example:

$message->addCustomHeader("List-Unsubscribe", "<mailto: [e-mail]>");

Above command adds a List-Unsubscribe header which allows users to unsubscribe from mailing lists by a button click.

send

Packs message body and headers, compiles latter with DKIM-Signature (if available) and sends mail to destination.

Example:

$message->send();