_sendmail

Send an email.

Syntax

_sendmail(args)

Parameters

args is a JavaScript object with specific property values for each argument to _sendmail.

Returned Value

0 if successful. Otherwise an error code. Note that if messages are queued and not sent immediately, the return code only reflects the success of adding the message to the send queue, not its success or failure to get sent. That information will then be available in the logfile for the DocOriginSendMailServer task. If the message is sent immediately, the return code may reflect the actual status feedback from the email server. The cURL program has an impressive set of capabilities and options and a long list of return codes. You can view this at cURL man page.

Description

ALERT: Don't let your message get trapped by a Spam Filter

The construction of your email message and the wording you use will affect how likely it is that a customer's spam filter may flag your email as spam. There are a number of websites with suggestions and tips on how to avoid this. Try a search for "how to avoid spam filters".

All parameters to _sendmail are defined as properties of a JavaScript object. For example:

var args = {};

args.To = "support@docorigin.com";
args.Subject = "Testing of DocOrigin sendmail command";
args.attach = "mytestfile.txt";
args.text = "This is my test message\nIt has two lines.";

rc = _sendmail(args);
if (rc != 0) _message("sendmail error - rc=%d", rc);

A "classic" is:

args.attach = _printer.getOutputFile("PDF");

Most email parameters can also be defaulted in the DocOriginSendMailServer.prm file. The parameters marked as (Mandatory) must be set either explicitly in the args definition or have a default value set in the DocOriginSendMailServer.prm file.

Args

The available parameters (args) are:

`args`.attach	A list of one or more file names separated by semicolons. These files are attached to the email. `_printer.getOutputFile("PDF")` is commonly used to refer to the output just produced.
`args.`bcc	Set a BCC (blind CC) address. This is a string containing one or more valid email addresses separated by semicolons.
`args.`cc	Set a CC address. This is a string containing one or more valid email addresses separated by semicolons.
`args.`checkaddress	Validate all email addresses before sending. This setting is typically set in the `DocOriginSendMailServer.prm` file.
`args.`*cidfolder*	A file folder on your computer where embedded html images are located. See HTML Image Embedding below for details. Defaults to the folder containing the HTML text.
`args.`from	(Mandatory) Set the sender's return address. This address must be present either in the args list or as a default setting in the `DocOriginSendMailServer.prm` file. Using Microsoft Exchange? See the note in Sending Mail.
`args.`*header*	(As of 3.1.002.06) Add an optional email header record to the email. This option can also be set in the `DocOriginSendMailServer.prm` file. Set this to a null string to override a -header setting in the `DocOriginSendMailServer.prm` file. If more than one header is required, separate the headers with "`\r\n`". This feature is useful if you require additional X-type headers in your emails.
`args.`hold	Prevents emails from actually being sent. If set to *true*, this parameter prevents the actual transmission of the emails. This option can also be set in the `DocOriginSendMailServer.prm` file to prevent any transmission of emails while testing the system. Messages that are queued will be placed in the queue but not sent. Note that if the `-hold` is then removed any queued messages will get sent.
`args.`*keep*	Determines whether to save the email that has been sent or to discard it. If set to *true*, sent email is stored in `-mailSentFolder`. This setting is typically set in the `DocOriginSendMailServer.prm` file.
`args.`html	Provide the message text as HTML-formatted text. This allows font typeface, size, bolding etc. as well as other HTML-style formatting. If the first character of the HTML string is an @ the string is assumed to be a filename. The contents of the file is read and used as the HTML message body. If both `args.`html and `args.`*text* are provided then the email message is sent with a "mimetype" of multipart/alternative which allows mail clients that don't support HTML mail to fallback to displaying the text email only.
`args.`subject	The subject line of the message.
`args.`*testMail*	(As of version 3.1.002.07) Causes all email addresses within the email (To, Cc, Bcc) to be replaced with this supplied email address. This is a quick way to test an email call and avoid sending emails to their intended recipients. This setting is also available on the program command line or the `DocOriginSendMailServer.prm` file.
`args.`text	Provide the message text as plain text. If the first character of the text string is an @ the string is assumed to be a filename. The contents of the file is read and used as the text message body. If both `args.`html and `args.`*text* are provided then the email message is sent with a "mimetype" of multipart/alternative which allows mail clients that don't support html mail to fallback to displaying the text email only.
`args.`to	(Mandatory) Set the To address. This is a string containing one or more valid email addresses separated by semicolons.
`args.`queue	Queue this message to be sent by DocOriginSendMailServer rather than immediately.

HTML Image Embedding

When you have specified an HTML message, Sendmail does some additional processing to attempt to nicely embed images into the HTML message body. Normally...

<img src="www.yourserver.com/yourimage.jpg" ...>

works as expected - fetching the image from your server and displaying it. However, if you encode this as

<img src="cid:yourimage.jpg" ...>

the file "yourimage.jpg" from your computer will be embedded into the email as a special attachment and referenced from there. The image is embedded into your HTML message without needing to reference any server. This can be useful for email viewers that might otherwise either inhibit image display or prompt the customer to turn on their display.

The string src="cid: must be exactly like that, the same case, quotes, etc. for this to work. If the args.html parameter references a file such as in

args.html = "@C:/DocOrigin/User/myhtmlfile.txt";

the cid image file is assumed to be in the same folder as the HTML. Otherwise, you can explicitly specify the location of the image file using the cidfolder option of _sendmail() or by setting the command line -cidfolder option.

ALERT: Interplay with -PDFCombineDocuments setting

The default setting of CombineDocuments is Yes for the PDF driver. That means that Merge keeps the output PDF file open for the entire duration of the job. You won't be able to send that combined document until End-Of-Job. If you wish to send individual document emails at End-Of-Document then ensure that you set:

-PDFCombineDocuments No