Auto Email

DocOrigin includes a feature to create sophisticated email messages and send them automatically from Merge. Using DocOrigin Design you can define the message body using many of the same drawing tools as used for other form designs. You can define the Email To, Cc, Bcc, Subject, and Attachment information as well. Email addresses can be pulled directly out of the data stream, or from an applicable form field. The email message can include images, links, and the usual bold/italic/font handling.

The same DocOrigin form file that contains the definition for a PDF document can also include all the necessary information to send that PDF as an attachment to a recipient. Or you can create only the email message itself, with or without additional attachments.

As of version 3.1.002.12, a newer, more integrated version of emailing has been included - as described below. Note that it is also still possible to code the sending of emails via the _sendmail script function. The Auto Email feature allows this to be done without employing script.

An example of the Auto Email feature can be seen in the DocOrigin/DO/Samples folder. The Sample_InvoiceEmail.xatw form can be opened in Design and tested using the PDF Preview command. If you want to actually send the emails (presumably to yourself for testing), you will need to ensure your system is set up for sending emails - see the SendMail page for more information on that.

Sample_InvoiceEmail uses its own sample data file, called SampleInvoice2.xml. It includes the recipient email address in it's <InvoiceHeader> <Email> data field. In this example, the email goes to a fictional email address (@example.com) - but you can copy and edit that .xml data file to send them to your own email address.

You can also preview the emails right on your own computer by adding the hold:yes option to the Mail Options setting in the Sample_InvoiceEmail form. The hold:yes option saves the email files (.eml) in the $U/Outbox/Hold folder. If you have a local email client on your desktop (such as Outlook) you can double-click on the eml file and view the actual email generated by DocOrigin.

How it Works

If you open the Sample_InvoiceEmail form, you'll see an _email_5 page in the form. The top of the page looks like this:

In this sample file, we've set the To address to the Email data field. This could also be a reference to any field within the current form using the usual [Email] notation. In this case, the Email data node has not been loaded into the form, so we just reference the data field directly. The To will be set to the value in the Email field, which is Kelly@example.com as shown below.

...
<InvoiceHeader>
   <CustomerID>Kelly</CustomerID>
   <Email>Kelly@example.com</Email>
...

The Attachments field has been set to [!PDF]. This is a special embedded text option in Merge that fetches the file name of the PDF file that Merge has just created using the other pages in the form. The result is that when the email is sent, the sample invoice is attached to the email.

The Mail Options are for you to pass along any special options to the DocOrigin SendMail module. As suggested above, you can set hold:yes to cause the email to be left in the $U/Outbox/Hold folder instead of emailing it right away. This is handy for testing.

The Plain Text Msg is an optional text message to include in the email just in case the recipient has a very old email system that doesn't handle a normal HTML email message.

The bottom portion of the page is where you can create the main email message for your customer.

In the email world, the main body of the email is typically created in HTML. Unfortunately, there are many email client programs your customer might be using to read email, and each supports a different subset of the HTML language. For this reason, DocOrigin has created a special internal EML driver that converts the message to a very generic version of HTML suitable for most email systems. When you run Merge against a form such as this Sample_InvoiceEmail.xatw, that internal EML driver is automatically used to create an appropriate HTML email message body from every pane in the _email_5 page (other than the _header_ pane which it uses for all the To/CC/Subject fields)

In our example there are two panes - the first just has the XYZ logo in it (more about this later on). The second pane is a typical text message to the customer, with inline substitutions of various field values from within the rest of the PDF document (on Page1 somewhere).

There are some additional rules regarding what Design constructs you can use in an HTML email message - see below.

You'll notice that the page width of this _email_5 page is somewhat narrower than most documents. The page width is used to control the final HTML message width. In this case to 5 inches (hence the name!) The message will be centered in the email viewer window (phone, tablet, browser, Outlook, etc.) Statistically today, most emails are read on cellphones. A 5" wide email is fairly convenient.

Below you'll see how the email looks in Microsoft Outlook:

Adding Auto Email to a Form

To add the auto email feature to a form, use the Insert>Fragment command, or the  button on the toolbar. Find the Default-Fragments library and the _email_5 page within that library and embed it in your design. (See the Fragments section for details on using Fragment Libraries.)

Designing DocOrigin Emails

There are certain rules about building email messages using DocOrigin. As noted above, the HTML supported by email systems is not as flexible as the HTML4 and HTML5 used in web browsers. The following information describes how DocOrigin can be used to create emails that will be supported by most common email clients.

• Emails in Design are constructed using a series of panes. Within each pane, you can use Text Labels, Fields, Groups, and Images. You cannot use Rectangles, Lines, or Barcodes.
• The Labels, Fields, or Images must be drawn as a single horizontal row of objects within each pane. You can, of course, have several panes, hence several "rows" of these objects. You can also use the Group object as a container for multiple vertically-stacked Labels, Fields, or Images. Note that groups cannot have side-by-side elements, only a vertical stack.

Here is a simple example in Design. It consists of a pane with three blocks of information: 1. a multi-line label; 2. a group (the rectangle) with 3 objects drawn vertically - two labels and an image; 3. finally at the right, a single image.

Here is the result as it would appear in an email message:

Images in Emails

When adding images to an email, the image itself must reside on your website, i.e. be URL-accessible. It will NOT be embedded into the message. You must add an Url tag to the image object in Design, specifying the location where your image can be found on your website. You should also include an Alt tag with alternate text to be displayed if the image cannot be loaded for some reason. (Keep in mind that some email recipients may block downloading of images in their email system.) For our sample above, we have set the following 2 tags on the images:

Alt The DocOrigin Logo
Url http://www.docorigin.com/DocOriginLogo.jpg

Links

Any object can have a web link added to it by setting the Link tag on that object. This means you can make images, fields, or text labels "clickable" so as to take the user to a webpage of your choosing.

Hyperlinks within a text label are also supported for Email generation. To do this, just highlight a section of a text label, right-click and select TagAs > Link from the popup menu.

Testing Your HTML Email

Like all things, but especially email that can slip out into the world, YOU MUST TEST THOROUGHLY. We can't do that for you but we do provide some means for you to 'engage'.

1. Use the aforementioned hold:yes option to keep the email from escaping until you have finished testing.
2. Use somebody@example.com as test email address to keep email from escaping.
3. If you are forgetful, use the -testMail option in your $O/DocOriginSendMailServer.prm file to redirect mail to a test address, hopefully, yours!
4. Enjoy the new buttons on the Design status bar to look at what you're producing.
   
5. It's always good to pore over the log file!
6. The <Html> button will give you a good view of the HTML email body. When the EML output configuration is used (often automatically) it produces both .html and .eml.
7. The <Eml> button will try to launch the generated .eml file. Hopefully, you have a program (often Outlook) associated with the .eml extension. (fyi: Since I don't have Outlook, I have installed the free CoolUtils MailViewer and have associated that with .eml. So far it has worked 'well enough' for me to see my various issues.) If you have put .eml files in the Hold folder you can review them there after the fact.
8. Don't forget to check out your plain text messages too. You are defining those, right!
9. Of course you can also redirect the email to yourself and see it in your own email client.
10. Get help! The folks at Email on Acid have lots of advice, including testing services. I'm sure we've run across others during development too. Do test across the variety of email clients that you might expect your recipients to have.
    fyi: this link might interest you: Email Client Market Share.
11. A tip. If you text edit .eml files you'll see lots of encoding, lots of =3D character sequences. You can make that easier on yourself by specifying Encodehtml:8bit in the Mail Options entry.
12. A tip. During development specify MailScanFolder:$$F in the Mail Options and you'll have the generated files more local to your work, not off in some Outbox folder. And you will be even more certain to take your emails out of accidental processing by DocOriginSendMailServer.

Beacons

It's quite common practice to include "beacons" in email. These are typically 1 pixel x 1 pixel transparent images which have an associated URL that automatically "calls back" to the host system to report that the email had been looked at, by whom, and related to what account, etc. Since these are HTML-based emails, that is no problem at all.

For your greater understanding, what is happening is that URL is processed by the email client/browser. It's in a <img...> element. The server should (must!) respond with an image. It can be small. The sample below does return a 1x1 pixel transparent image. If you don't return an image your user may get a red X.

To insert a beacon into your HTML email design simply put an image label in one of the panes and define an Url tag for that image. The Url tag refers to a web server request handler for the beacon's message. For example:

Url: https://example.com/beacon.php?[!Time]&data=[Transaction_ID]&account=[Account_ID]...
      ...&user=[CustomerName]

My example uses PHP but you can use whatever web technology you like. As you can see, you can embed information to pass to the "beacon" using any of the usual Auto/Embedded Fields notation. When Merge resolves the URL, it automatically encodes it such that you don't have to worry about breaking the url-encoded syntax with your field inserts. The PHP will receive it in unencoded fashion.

Presumably, that PHP will extract all the elements in the beacon's message, and likely store them away in a database, possibly initiating further server-side action as befits the host's desires. It is not possible for DocOrigin to supply that custom server-side technology. The following is a mere 'proof-of-concept' PHP to show that the email-embedded beacon is doing its job.

Download the sample beacon.php (as a .txt file) below. (Depending on your browser, the text file may open in your browser. Then, right-mouse-click on the page and select Save As...)

beacon.txt

Right-mouse-click on the 1x1transparent.png image below and select Save Image As... (Note: a frame was added to see the small, white image and select)

Just the HTML Please

Maybe you just want this cellphone-friendly HTML to email later, or to post on a website. Clearly, that HTML is generated; you can see it via the <Html> button in the status bar. But normally it resides with an obscure name in the DocOrigin temp files folder. You can get just the HTML into a known place by using the Default-EML.prt output configuration directly and specifying the -EMLOutputFile=xxxx.html option. The desired HTML will be placed in the desired location with the desired name.

See Also

_sendmail scripting alternative
SendMail for configuring the DocOrigin email subsystem