<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fEmail">Class Documentation</a>''' - <a href="/api/fEmail">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fEmail.php" target="_blank">Source Code</a>
<<toc></toc>>
- '''fEmail''' - fMailbox - fSMTP
)))
The fEmail class provides an interface to very easily send well-formed emails with UTF-8 content, HTML, attachments and S/MIME encryption and signing. fEmail uses PHP’s built-in `mail()` function by default, but can be used with fSMTP for mass emailing or mailing via a remote mail server.
Creating a new email is as simple as making a new instance of fEmail:
fEmail supports `To:`, `CC:` and `BCC:` recipients through the methods ::addRecipient(), ::addCCRecipient() and ::addBCCRecipient(). Each method requires a single parameter `$email` and accepts a second optional parameter `$name`. The add methods can be called any number of times to add any number of recipients:
If need be, all regular, CC and BCC recipients can be cleared by calling the method ::clearRecipients().
When sending a message you will also need to set the `From:` address via the method ::setFromEmail(). The first parameter, `$email`, is required, however the second parameter, `$name`, is optional. Unfortunately the implementation of `mail()` on Windows does not allow setting the `$name` parameter. A `$name` will work on Windows if you use fSMTP.
It is also possible to set the `Return-Path:` header on almost all servers. This email address is listed as the “true” source of the email and will be the recipient of any bounces or delivery notifications. The method ::setBounceToEmail() sets this address with just a single parameter `$email`:
All email must have a subject and body set by the methods ::setSubject() and ::setBody(). Both of these methods accept a single parameter, a UTF-8 string.
The ::setBody() method can also take a second parameter, `$unindent_expand_constants`, which is a boolean. When this parameter is `TRUE`, the body will be unindented as much as possible, and will have all `{CONSTANT_NAME}` strings replaced with the constants value, if defined. This parameter is useful for inline generation of bodies where you don’t want to deal with the issues of having a fully unindented end to a `HEREDOC` string.
For example, the following PHP:
would create the email body:
Without the parameter, the body would be:
The `HEREDOC` equivalent of our desired output would be:
In short, the `$unindent_expand_constants` parameter allows for cleaner PHP with logical indentation levels.
When dealing with a more complex body example, or wishing to separate the email templates from your PHP, the method ::loadBody() can be used. This methods accepts two parameters, the `$file` to load the body from and an array of `$replacements` to be performed.
The `$file` parameter can be either a file path or an fFile object. The `$replacements` parameter should be an associative array with the terms to search for being the keys and the strings to replace them with being the values.
Please note that the terms to search for do not have to be in any particular format, a simple `str_replace()` call is used to do the replacements.
It is also possible to add an HTML version of the body by passing it to ::setHTMLBody(). This HTML content should be encoded using UTF-8:
Just like ::loadBody() for the plaintext body, the HTML body can be loaded from a file via ::loadHTMLBody(). This methods accepts two parameters, the `$file` to load the body from and an array of `$replacements` to be performed.
The `$file` parameter can be either a file path or an fFile object. The `$replacements` parameter should be an associative array with the terms to search for being the keys and the strings to replace them with being the values.
Please note that the terms to search for do not have to be in any particular format, a simple `str_replace()` call is used to do the replacements.
When using an HTML body, it is possible to add files to the email that can be referenced in the HTML, but do not appear as an attachment. Such related files are added by the ::addRelatedFile() method. This method requires either one or two parameters: `$contents`, or `$contents` and `$filename`. If `$contents` is an fFile object, no `$filename` is necessary. A URL will be returned for direct embedding into HTML `src` or `href` attributes.
There is an optional third parameter, `$mime_type`, which can be used to fix incorrect detection of the mime type of a related file.
Attachments can be added to an email by calling the method ::addAttachment(). The method requires either one or two parameters: `$contents`, or `$contents` and `$filename`. If `$contents` is an fFile object, no `$filename` is necessary.
There is an optional third parameter, `$mime_type`, which can be used to fix incorrect detection of the mime type of an attachment.
There is no limit to the number of attachments.
The fEmail class provides support for encrypting and signing messages using S/MIME. To encrypt a message, the PEM-encoded public certificate will be needed. To sign a message, the PEM-encoded private key will be needed. To encrypt and sign you will need both (but not for the user). Please see Obtaining a Secure Certificate/Key Pair for information about how to get the necessary files.
To encrypt a message, call the method ::encrypt() and pass the path to the recipient’s PEM-encoded public certificate:
To sign a message, call ::sign() and pass in the sender’s public certificate path, private key path and private key password (if applicable):
If you call both `sign()` and `encrypt()` (in either order), the message will be signed, then encrypted and then signed again. This is the most secure method, however certain older email clients may not open such emails.
To send an email, simply call the ::send() method.
The return value is the generated `Message-ID` header for the email, which can be used with the `In-Reply-To` header for tracking replies. The fMailbox class provides functionality for checking and parsing email.
If there is a need to add custom headers to an email message, the method ::addCustomHeader() will accept the header `$name` and `$value`. The `$value` should be a plain string - the method will handle any necessary encoding or line wrapping necessary to keep the headers standards-compliant.
It is possible to set multiple headers at once by passing an associative array to ::addCustomHeader().
On some linux/unix server running qmail as the sendmail replacement, you may experience issues with emails looking corrupted to the recipients. This will often take the form of equal signs (=) appearing throughout the content and lines being wrapped in odd places.
The technical cause of the issue is that the qmail sendmail binary is automatically replacing every line feed (\n) with a CR-LF (\r\n) because the email specifications require emails use CR-LF and linux uses LF as the line ending. Qmail is trying to ensure you are sending emails that meet specifications, however it is not checking to see if the email already has the proper line endings.
The first way to try and solve this issue is to use fSMTP and connect to the SMTP server on `localhost`. This by-passes the command-line interface to qmail:
If that is not possible, the static method ::fixQmail() should fix the issue. On servers where `open_basedir` and `safe_mode` are not in effect, fEmail will make a commandline call to sendmail and will replace all CR-LF with just LF. If that is not possible, fEmail will simply replace all CR-LFs with LF, however emails with long headers may still have issues.
Normally you would only enable this fix if you experience the issue. Since the fix affects all instances of fEmail, you’ll normally want to call it in a configuration file.
In certain situations it may be necessary to validate an email address when not using fValidation or fORMValidation with the ORM. The fEmail class provides two regular expression constants to help with the task.
These regular expressions are designed to fully match the `mailbox` specification of RFC2822 Section 3.4 except for allowing comments and folding white space. Quoted strings are supported along with the `+`, `-` and other special characters.
Below is an example of some of the various valid email address formats that are supported:
The two constants are `EMAIL_REGEX` and `NAME_EMAIL_REGEX`. `EMAIL_REGEX` will match an email address, while `NAME_EMAIL_REGEX` will match a `name <email></email>` string.
`EMAIL_REGEX` captures 3 subpatterns in the following format:
- ![0]: The whole email address - ![1]: The part of the email before the @ - ![2]: The part of the email after the @
For example:
will output the following:
`NAME EMAIL_REGEX` captures 5 subpatterns in the following format:
- ![0]: The whole name and email address - ![1]: The name - ![2]: The whole email address - ![3]: The part of the email before the @ - ![4]: The part of the email after the @
For example:
will output the following: