Sending Mail
Conceptually, it is pretty easy to understand the notion of using document generation to produce a document and then using an email tool to send that output somewhere. Nothing magical there, also totally unintegrated, requiring two tools to understand and peer into the data to figure out what to do.
Far more exciting is the ability to send mail from within a form. As the Multiple Outputs topic has shown, DocOrigin Merge can produce all sorts of outputs and can specify where those outputs are to go. One of those distribution mechanisms is "email".
The email addresses are surely in the same data stream as Merge has just processed, and therefore they are in the Document DOM, easy pickings for use with the _sendmail() function. How does this happen?
The place for orchestrating the sending of mail is the End-of-Document event. You could use any object, but the form object itself is likely the one whose End-of-Document event you should put the script into. Sometimes folks use the email address field as the object to hang the script off of. Consider...
if (_document.customer.email._value != "") {
var args = {};
args.to = _document.customer.email._value;
args.from = "CustomerRelations@mycompany.com";
args.subject = "Your statement: " + NCLI._value + NATR._value + NSEQ._value;
args.attach = _printer.getOutputFile("PDF");
args.text = "@$$F/PlainTextEmail.txt";
args.html = "@$$F/HtmlEmail.txt";
// args.cidfolder = "$$F";
// args.hold = "Y";
_sendmail(args);
}
What's happening in that code? Well, really it's just setting up the arguments to a _sendmail() call, which it then makes on line 11. See Sendmail and _sendmail.
Line 1 predicates the whole thing on whether we have an email address to send to. You may have other criteria. You may even dynamically look up the email address based on some other customer account id, or some such thing. The intent is pretty obvious though.
The Email From Address
A from address is required but is often set in the Sendmail Configuration .prm file. The address can be in the format: "friendly address <actual address>" as you will often see on emails these decades. If you provide only the actual address without it being enclosed in angle brackets, then the address will automatically be suffixed with <actual address>, essentially a repeat.
Some versions of Microsoft Exchange do not have the wit to handle current style email addresses that include the friendly name. If you have issues with your from address and are using Exchange, then specify your from address as "<actual address>". When DocOrigin sees the '<' it will presume that a friendly name has already been provided and so will not add any suffix. That lets Exchange be happy.
The Email Subject
In line 5, you can come up with any subject line you like. You can be bland, or you can personalize it based on the data at hand.
The Email Attachment(s)
Line 6 is pretty simple; you want to attach the PDF file that was just produced for this document. Dead easy. Want more than one attachment? Perhaps, the information in the data "suggests" that you attach a specific brochure. The args.attach value can be a semi-colon separated list of attachments. So, attach away.
The Email's Text-Based Body
Line 7 could be as simple as:
args.text = "This is your statement";
but that wouldn't be very communicative. You can formulate the text-based body of your email any way you like. Clearly, you could build up a string that contained all sorts of information taken from the data stream. This particular example says to get the text-based body of the email from a file called PlainTextEmail.txt which resides in the same folder as the form design (that's what $$F means).
One way to come up with the text-based body for an email is to define a text label in the form and have it include as many [square bracketed] field references as applicable. Then the code can be something like: args.text = _document.emailstuff.bodytext._value;. That postulates a pane named emailstuff that is marked invisible in the form design. It makes it easy to design a text-based body and see what it looks like on the Design canvas. But scripting works too.
There's a clever combination that we owe to an SE. The label text field sets its value to [@$$F/PlainTextTemplate.txt]. That template may include the usual [square bracketed] field references. The cool thing here is that those contents get read into the text label and then Merge automatically does [field] substitution. This makes it pretty easy for a non-form-designer to contribute to the overall effort. The relevant department can not only contribute but take control of what the email message text will say. No form design skills are required. When that department posts the latest version of the referenced template file, all will flow nicely, with no forms department involvement required.
As of 3.1.001.01 much of this is more easily provided by the _email_ fragment introduced in that version to facilitate sending email without using any script. See Auto Email.
The Email's HTML-Based Body
Line 8 is really just more of the same. Just that here we are supplying the value for the HTML-based portion of the email body. It is not a requirement to provide both textual body, and HTML-based body, but perhaps it will offer a competitive advantage to do so. Again an external department can take on the effort, and gain the control of defining what those vital contact points with the customer look like.
Images in the Email HTML body
Line 9 is commented out but it brings to mind a powerful feature related to the HTML-based body. The html body can include embedded image references. These take the form of
<img src="cid:aFileName.jpg" />
Perhaps it would include a height and width specification too, your choice, normal HTML.
The DocOrigin _sendmail() function will detect such constructs and embed the nominated image, or images into the mail package that is sent. And _sendmail() will inject the necessary plumbing to have that image show up where it is supposed to. Likely the recipient will get an "Images are not shown below, click here to show images" message in his email -- depending on his email client software. Normal operations; the images are visible.
Where the cidFolder specification comes in is to tell _sendmail() where to look for images. Mind you, most often the cidFolder specification would be housed inside the DocOriginSendMailServer.prm file. But that choice is yours.
Summary
In sum, you can produce a very complete, and tailored e-mail message, and you can have external departments take ownership of many of the details. Do recall that this is happening as the Merge run proceeds, no separate after-the-fact process is involved.
If you do want to do after-the-fact-processing, then feel free to use RunScript and its ability to invoke _sendmail() in the same way -- though it wouldn't have access to the Merge-created Document DOM since it would be running as a separate process.
If you wish to send an email attaching a combined PDF, then that needs to be done at the End-of-Job event (not End-of-Document) since the PDF will be open throughout the run, not being complete until end-of-job.
Debugging
Line 10, args.hold = "Y"; is strictly for debugging. With it you can force the DocOriginSendMailServer to not send the message but to keep it in the "outbox". That way, you can examine the mail packet during your development phase and see if all is well. The line would certainly be commented out in production. This could be an across-the-board debug setting in DocOriginSendMailServer.prm or, as is shown here, it may be that only certain messages are to be held up.
