Function: Send_email

The send_email function uses a JSON object to specify all parameters needed to complete the email sending. This implies server connect parameters as well as the recipients, the subject, body text, and attachments. The idea is to make it easier to set up the mail-sending instead of specifying numerous parameters to the function call.

Prototype:

string result = send_email(JSON object);

Parameters:

Object key  Type  Description
server.host  string  The host name of the SMTP server to use
server.user  string  Username for the logging in to the SMTP server
server.password  string  Password
server.port  string  Port number for connection: default 587
from  string  From email address
to  string  To: comma separated strings of e-mail addresses, or an array of recipients
cc  string  Copy to: comma separated strings of e-mail addresses, or an array of recipients (optional)
bcc  string  Hidden copy to: comma separated strings of e-mail addresses, or an array of recipients (optional)
subject  string  The subject of the email
body.plain  string  The plain text version of the body (optional)
body.html  string  The HTML version of the body (optional)
body  string  as an alternative to the two above, only the HTML version.
attachements  array  array of attachments, as strings. Use posix path.

Return value: Type string : "OK" if sending went well, otherwise an error message.

Example:

JSON email; 
email["server"] = JSON ( "host", "smtp.example.com", 
                        "user", "myUser", 
                        "password", "myemailpassword", 
                        "port", "587"); 
email["from"] = "john.doe@example.com"; 
email["to"] = "ola.normann@example.com"; 
email["cc"] = "kari@example.com"; 
email["bcc"] = "bcc.copies@example.com";
email["subject"] = "Order confirmation";
email["body.plain"] = "Dear Ola, thank you for your order....."; 
email["body.html"] = "<html>
<body>
<h1>Thank you for your order</h1>
...
...
</body>
</html>";
email["attachements[]"] = "/Users/john/Desktop/orderconf.pdf"; 
email["attachements[]"] = "/Users/john/Desktop/mySecondAtt.pdf"; 

// Send the email
string res = send_email(email); 
if ( res != "OK") then
    alert ("Mail sending error: " + res); 
end if

HTML with inline images

Having HTML image tags in your HTML version of the body text requires the source to be a file:// type URL. The send mail searches the body text for such image tags, add them as attached files, and rewrites the image tag to reference the attachment. The attached images are stored in a "multipart/related" section of the email content.

From html content before sending: 

<p>Best Regards,<br/>
<img src="file:///Users/ole/.../mylogo-2.png"/>

After sending (What arrives at the recipient's mailbox: )

<p>Best regards,<br/>
<img src="cid:7aee0606-4614-4d83-b4a2-8dbc3368b8a5"/>
...
...
</body>
</html>
--=REL_aaa93cb9-511c-4d67-8748-ea337e440449_
Content-Transfer-Encoding: base64
Content-Disposition: inline; filename="mylogo-2.png"
Content-Type: image/png; name="mylogo-2.png"
Content-ID: <7aee0606-4614-4d83-b4a2-8dbc3368b8a5>

iVBORw0KGgoAAAANSUhEUgAAAMgAAAA4CAIAAAA3qCDQAAAKrmlDQ1BJQ0MgUHJvZmlsZQAA
...
...

The email part handling

The function creates a multipart email automatically based on the content in the various JSON elements supplied.

The most comprehensive content would be an HTML mail with related images and attachments, it looks like this: 

mail header fields (to, cc, subject, date, X-mailer, etc)
Multipart/mixed: 
        mixed Multipart/alternative:
                alternative Plain content
                alternative Multipart/related: 
                    related HTML-content
                    related image-1
                    related image-2
        mixed attachement-1
        mixed attachement-2
        ...

Use of the function together with markdown text

It is a good idea to produce the HTML content using the markdown2html ACF function. It requires a work folder containing the themes for the HTML generation. The themes folder is available in the demo download of the email download. The work folder usually resides on the user's local disk, but can also be on a shared volume. Its path is set up using the set_html_root_path ACF function before applying the markdown2html function. The markdown content is stored on a temporary file, and the name of the HTML file along with the style names are parameters to the markdown2html.

The produced HTML can be tweaked to make the desired result. For example, if you want to set a maximum width of inline images, you could use a regex function like this: 

htmlContent = regex_replace("(<img[^>]*)(>|\\/>)", 
            htmlContent, "$1 style=\"max-width: 95%; max-height: 95%;\"$2");

This will insert the styles before the closing tag of all images in the htmlContent, ensuring it's not wider than the enclosing container.

Why do we send a plain version of the e-mail as an alternative?

Most modern e-mail clients can correctly display HTML e-mails. However, some simpler e-mail clients or some web-mail clients cannot, and they will display the plain version instead. It will also improve the deliverability of the email, making the email composition adhere to the standards for sending email. Many spam robots use a simpler mail-sending system that does not make all the required parts.

References: