Use Inline Graphics in Emails
For a client I built an example that put together an email for us. This email should show a picture as header and another picture as footer by default. These pictures were included via inline graphics. How this works I would like to show you now.First of all I want to write the text for the mail in my project and have the possibility to attach attachments. The mail should automatically be displayed as a preview in a Web Viewer with the header and footer. With a click of a button the mail should be sent to a list of email addresses. The header and footer as well as the data to send our e-mail (username, password and mail server) are located in fields.
Let's start with the preview
To do this, we first read our formatting text from our textview. The text is converted into HTML with the GetAsCSS function. The header is placed before our text and the footer is after our text. So let's first build in placeholders, which we will replace later. Around this text we can then build the HTML structure with HTML and body tag.
Then we replace the placeholders in our HTML and insert the images. So we set image containers with the images. We must then Processes image references in HTML. That means all cid: links are found. : and / are replaced with dash.
Set Variable [ $HTML ; Value: GetAsCSS ( Emails::Text ) ]
Set Variable [ $HTML ; Value: "$$Header$$" & $HTML & "$$Footer$$" ]
Set Variable [ $HTML ; Value: ""&$HTML&"" ]
Set Variable [ $HTML ; Value: Substitute($HTML; "$$Header$$"; "<img src=\"cid:Header.png\">") ]
Set Variable [ $HTML ; Value: Substitute($HTML; "$$Footer$$"; "<img src=\"cid:Footer.png\">") ]
Set Variable [ $HTML ; Value: MBS("EmailParser.ProcessImageReferences"; $html) ]
We need all our sources in one folder. Because this we add a folder Email in the temporary Folder and write the HTML as file and the Footer and Header to this folder. We give the following names to the image files: cid:Header.png and cid:Footer.png. We need the cid in front of the name to include the inline graphic.
If we work on a windows system we need to adjust the file paths.
Set Variable [ $htmlFile ; Value: Substitute($htmlFile; "\\"; "/") ]
On Mac we need to make an URL out of the File path:
Set Variable [ $htmlFile ; Value: MBS( "Path.FilePathToFileURL"; $htmlFIle )
This Path we then set to the WebViewer and can see the Preview.
Sending the Mail
The script for building and sending the mail looks very similar at the beginning as the HTML is built in the same way. But we do not write the data to a temporary folder as this data will be attached to the mail in a later step.
To build the mail we use the functions from the topic SendMail. First we create a working environment for the mail. This is then addressed with the delivered reference in later steps.
Set Variable [ $Mail ; Value: MBS("SendMail.CreateEmail") ]
To send the mail we have to enter information about our server, the password and the user name from which we want to send the mail.
Set Variable [ $r ; Value: MBS( "SendMail.SetSMTPUserName"; $Mail; Emails::UserName ) ]
Set Variable [ $r ; Value: MBS( "SendMail.SetSMTPPassword"; $Mail; Emails::Password ) ]
Set Variable [ $r ; Value: MBS( "SendMail.SetSMTPServer"; $Mail; Emails::SSLServer ; 1 ) ]
The 1 in the parameters at the Server setting, sets that we want to use SSL. If we want to use TLS we pass 0 and configure later the CURL connection for TLS. Looks often strage, but the question is whether the first data package sent is encrypted or not. And for TLS with StartTLS command, the first package is plain text greeting the server. Then we ask the server for capabilities, decide on the encryption scheme and continue the encrypted transfer.
To add a recipient, the SendMail functions offers us several options, depending on what type of recipient we want to add. We can choose between a simple recipient, a copy recipient or a blind copy recipient. We have the corresponding functions for this: SendMail.AddTo, SendMail.AddCC and SendMail.AddBCC
If you have stored in your database what type of recipient the mail address will be assigned to, you can use the SendMail.AddRecipient function. In this function you can specify in the second parameter which type the recipient should be. With all these functions you can also optionally specify which name should be displayed so that instead of the mail address SamMiller123@xyz.com e.g. Sam Miller is displayed.
If you want to specify a separate mail address to which replies will be sent, you can use the SendMail.AddReplyTo function or specify „ReplyTo“ in the SendMail.AddRecipient function.
You can add not only one addressee but several. So that you can also send batch mails. To do this, build a loop over your recipients and add them to the desired group. The functions can also be called several times for one mail.
With SendMail.SetSubject you enter the subject and with SendMail.SetHTMLText you enter our already assembled HTML content text.
Set Variable [ $r ; Value: MBS( "SendMail.SetSubject"; $Mail; Emails::Subject ) ]
Set Variable [ $r ; Value: MBS("SendMail.SetHTMLText"; $Mail; $HTML) ]
Add Attachments
The only thing missing from the mail build are the attachments. These we want to add now. Let's start with the attachments for header and footer from the container. These are attached like normal attachments with the function SendMail.AddAttachmentContainer. The SendMail.AddAttachmentContainer function is structured as follows:
MBS( "SendMail.AddAttachmentContainer"; EmailID; Container { ; Name; MimeType; InlineID } )
At first we set the Mail reference and the container in which the attachment is stored. In the optional parameters we can set the name of the attachment (If we don’t set the filename is used), the MimeType and the InlineID. Because we have our Header and Footer as Inline Graphics we must set the last optional Parameter. The ID is that what we set in the HTML after „cid:“. For example cid:Header.png. That means that our ID for the Header is Header.png
We can append header and footer data with the following lines:
Set Variable [ $r ; Value: MBS("SendMail.AddAttachmentContainer"; $Mail; Emails::Header; "Header.png"; "image/png"; "Header.png") ]
Set Variable [ $r ; Value: MBS("SendMail.AddAttachmentContainer"; $Mail; Emails::Footer; "Footer.jpg"; "image/jpg"; "Footer.jpg") ]
The remaining attachments can also be attached using this function. Here we do not need the inline ID anymore. If you want to add multiple attachments you can do this again with a loop.
Now the mail is ready and can be sent. For this we build a new CURL connection. All required data are already available in our mail, so we can call SendMail.PrepareCURL to pass the settings. Then we call the CURL.Perform function to send the mail.
Set Variable [ $CURL ; Value: MBS("CURL.New") ]
Set Variable [ $r ; Value: MBS("SendMail.PrepareCURL"; $Mail; $CURL) ]
Set Variable [ $r ; Value: MBS("CURL.Perform"; $CURL) ]
For every MBS function, you can check if that MBS function returns an error by calling MBS("IsError") after using the function. At this point it is useful because you can see if there was a problem sending the mail and display this in a dialog for example.
Because we have worked with references in the Mail and also in the CURL. We have to make sure that these are free again.
Set Variable [ $r ; Value: MBS("CURL.Release"; $CURL) ]
Set Variable [ $r ; Value: MBS("SendMail.Release"; $Mail) ]
I hope you enjoy using these functions in your solution. Stefanie is available fo questions, training via screen sharing or to help with a sample database.