SendMail Configuration
SendMail must be specifically configured for each user environment. The default settings are defined in the DefaultDocOriginSendMailServer.prm. (Note that despite the "Server" at the end of this file name, the settings are in fact for both the immediate sending of emails and the queued sending of emails.) This default file is supplied with your installation. To make changes you should make a copy of any required sections of the file and store it in your .../User/Overrides folder under the name DocOriginSendMailServer.prm. This new file is automatically referenced after DocOrigin reads Default-DocOriginSendMailServer.prm. You can make any changes you like to the version of the file in .../User/Overrides - they will override the default version of the file.
The DocOriginSendMailServer.prm file is a text file and contains vital internal comments as to what each of the settings is for. You will, at the very least, need to change the following:
-smtphostto be your email server-smtpuserand-smtppasswordto your account- and possibly
-smtpportif your email server uses a different port number. - You should also modify the -from the default setting to be one of your email accounts. The -from can also be set explicitly on each call to
_sendmail.
Alternatively (as of 3.2.001.01), for more flexibility, you may specify command-line parameters which will override settings found in the PRM file.
DocOriginSendMailServer will take the information found in the message scan folder, typically .../User/Outbox, establish a connection to your specified SMTP server, and send the message. Upon completion, the message files are deleted or moved per your configuration settings. When DocOriginSendMailServer has processed all messages from the scan folder it shuts down.
Immediate or Queued
Email may be sent either 'immediately' or 'queued'. Sending email immediately is rather slow since a connection to the email server needs to be made and the calling script must then wait until the mail is actually sent. For this reason, it is often preferred to send email in a queued fashion. This puts the needed files in a folder, usually .../User/Outbox, and a separate program is launched to look after the sending of the email (or possibly many emails); meanwhile, the calling script will carry on processing with no waiting.
The folder where queued emails are put is defined by the -mailscanfolder option as specified in the DocOriginSendMailServer.prm override file. Typically it is .../User/Outbox.
You specify your wish to send emails immediately via a -sendmail immediate directive. More likely, for performance reasons, you would specify -sendmail queue in order to queue the sending of email while your script carries on processing. These options can also be specified on a per email basis by supplying the .queue property as true or false in your _sendmail function call.
var args = {};
args.To = ...
args.Subject = ...
args.etcetera ...
args.queue = false; // Send this email immediately, I'm willing to wait
_sendmail(args);
Similarly, with the Auto Email system, set the Mail Options to either queue:Y or queue:N.
Messages that are sent immediately are processed by the _sendmail function itself. No scanning of folders is involved. _sendmail launches cURL on its own, waits for it to complete, and then does the necessary housekeeping.
Messages that are queued, are put, by _sendmail, into the .../User/Outbox folder. There is a pair of files. One has a .eml extension and contains the entire email package including any attachments. The other file has a .scan extension and contains the instructions for cURL to use. Once the files are placed in that folder, _sendmail will launch DocOriginSendMailServer so that it can process any messages that are in the nominated scan folder, while the script that called _sendmail continues on without waiting. DocOriginSendMailServer scans the folder for *.scan files and processes each email accordingly.
Aside: As it happens, emails sent immediately do also put a pair of files in the Outbox. One is the usual .eml file and one has a .config extension. DocOriginSendMailServer never sees those files. _sendmail handles them directly by using cURL on them itself.
Creating but not Sending and Email (-hold)
You can tell the email system to hold an email and not send it automatically at all using the -hold options (arg.hold = true; in script, or Mail Options of hold:Y for the Auto Email feature) This causes the .eml file and an associated .scan file to be placed in a separate /Outbox/Hold subfolder. This can be handy if you are testing a form or script and you don't want to actually send it - just look at it. If you have a desktop email client (such as Outlook) you can double-click on the .eml file and see the email as it would be displayed if it had been sent.
If you move the .eml file and its associated .scan file back to the parent Outbox folder, it will then be sent the next time DocOriginSendMailServer is run. (It requires no parameters, so it is easy to run!)
Post-Send Housekeeping
If the transmission of a message is not possible due to some parameter error or email system error, the pair of files is (as of 3.0.003.24) moved to the subfolder as defined via the -mailErrorFolder directive in your DocOriginSendMailServer.prm file. The default is to go a sub-folder named Error. This folder will be immediately under the scanned folder, hence it is typically .../User/Outbox/Error. Prior to 3.0.003.24, the .scan (or .config) file would've been left in place but renamed to have a .ERR extension.
If the email send is successful then the pair of files will either be deleted or renamed/moved. Normally they would be deleted. This is controlled by the -keep option in the DocOriginSendMailServer.prm file. If -keep is not specified, it is assumed to have the value No and hence the successfully sent email files will be deleted. If you are not queuing the emails (i.e. args.queue = false this can also be controlled on a per _sendmail (or Auto Email) basis by specifying the .keep property as either true or false.
If you do choose to keep the files even after a successful send... before 3.0.003.24, the .scan file would've remained in place but be renamed to have a .DONE extension. As of 3.0.003.24, the pair of files would be moved to the subfolder identified by your -mailSentFolder option. By default, that has the value Sent and hence the files are moved to folder ../User/Outbox/Sent.
During initial development, it may be useful to specify -keep Yes in order to look at the email files that were produced. However, if you do so, do remember to empty out that folder from time to time as folders with many many files can slow the system down. The folder name specification can have the usual date substitution % variables in it (e.g. %U is replaced with the current week number). In that way, multiple "Sent" folders can be created each covering a certain period of time. See File Naming Conventions for file/folder name syntax.
Prior to 3.0.003.24, if DocOriginSendMailServer encounters a timeout from the SMTP server, (either it's not available or may be overloaded), the message remains in the scan folder and DocOriginSendMailServer will attempt to resend it at a later time. The -pause setting below can be used to control when this resend is attempted.
As of 3.0.003.24, cURL is directed to retry the send -retry times. If it fails, the files are copied to the -mailErrorFolder folder.
Parallel Connections
Prior to 3.0.003.24, many instances of DocOriginSendMailServer may have been running simultaneously. However, their invocation of cURL resulted in only a single connection to the email server being made. Other overheads were encountered as well.
As of 3.0.003.24, only one instance of DocOriginSendMailServer is allowed to run. If _sendmail launches a second instance, that second instance will detect the first instance and simply exit. The one instance of DocOriginSendMailServer scans the outbox folder for .scan files and will launch up to -maxProcesses instances of cURL in parallel to process the messages. If the software generating the emails gets ahead of DocOriginSendMailServer, the latter will find many email messages to send but will process them in a parallel fashion. There is a hard limit of 64 simultaneous connections, though your email server may have a lower limit.
As always, DocOriginSendMailServer exits when it finds no further email messages to send (i.e. no more .scan files). _sendmail launches DocOriginSendMailServer only after it has created the pair of files (.eml, .scan) in the outbox folder.
Option List
The following command line parameters control the DocOriginSendMailServer process. There is a Default-DocOriginSendMailServer.prm file located in the DO/Bin folder of your install. This prm file will automatically be loaded when DocOriginSendMailServer starts running. It is also loaded by any call to _sendmail. There are some default settings that come with your installation. You must make a copy of this file and place it in the .../User/Overrides folder under the name DocOriginSendMailServer.prm – do notice the dropping of the Default- prefix. This becomes your custom settings file. Put any overrides to the default settings in this Overrides file (if one exists, be sure to remove the @@ reference at the bottom of the copied file).
The following parameters are in addition to those listed in the _sendmail() function description and are specific to the Windows platform. Fields marked as MANDATORY must be defined either in the default parameter file or passed via a _sendmail() args setting or via an included parameter file.
-smtphost, -smtpuser, and -smtppassword settings are fictitious and MUST be overridden.Setting | Description |
|---|---|
-checkAddress Yes/No | Do basic email address format validation. |
-encode password | If DocOriginSendMailServer is run with this as its only command line parameter, (not from the prm file), an encrypted version of the supplied password is displayed. You can use this in conjunction with the |
-from emailAddress | The default "from" address to be used. The smtp server may require that this be a valid address for your email server. This setting can be overridden in the _sendmail() function. Using Microsoft Exchange? See the note in Sending Mail. |
-header header record | Add this additional header to all emails sent. This setting can be overridden in the |
-logfile filename | Standard DocOrigin logfile entries will be written to this file. We think it is a good idea to nominate a specific logfile for DocOriginSendMailServer log messages, rather than use the omnibus, ad hoc, $L/DocOrigin.log. You probably won't want your DocOriginSendMailServer log messages interleaved with other simultaneously running processes. MANDATORY |
-message filename | Standard DocOrigin error message file. MANDATORY, but automatically supplied in the DefaultDocOrigin.prm file. |
-mailscanfolder fileFolder | This is the name of a folder where the messages are stored by calls to |
-pause seconds | This causes the DocOriginSendMailServer to wait a few seconds before trying to resend messages that have failed to send because of an smtp timeout. The default is 60 seconds. (Obsolete as of 3.0.003.24) |
-proxyport number | If you are using an SMTP server that requires a proxy or SSL link, you must supply a ProxyPort number. This is a port# on your computer and can be any currently unused number such as 8801. |
-smtphost hostname | This is the SMTPHost name provided by the email server. MANDATORY |
-smtpuser name | Many SMTP servers require authentication - a way to ensure that only valid users of their mail server can use it for sending messages. Typically this can be any email user/password combination that has been defined on the server. If your server does not require authentication override this setting with |
-smtpPassword password | The associated password for the SMTPUser setting. The password can be entered in either plain (readable) text or as a specially encrypted string to protect it from casual viewing. If the password is entered in plain (un-encrypted) text, it must be preceded by an exclamation mark as in:
To create an encrypted password string you must run the DocOriginSendMailServer program in a command shell or bat file with the command line option of -encode followed by your password. |
-smtpport number | This is the SMTP port# specified by your SMTP service provider. Often this is port 25, but many servers do use other port numbers. MANDATORY |
-maxProcesses number | DocOriginSendMailServer will employ multiple parallel connections to your email server, by invoking multiple instances of cURL, one per message. This has a dramatic effect on email send performance. The maximum number of processes is 64. A value of 20 seems to perform quite well. |
-maxRate number | If set, message rate is limited by the number per minute. Throttling state is maintained via "throttling.state" file in mail scan folder (usually $U/Outbox). (As of 3.1.002.06) |
-queue true/false (or Yes/No) | This tells |
-keep No/Yes | This tells DocOriginSendMailServer whether to delete the .eml package after it is sent, or rename it to a .DONE extension (as of 3.0.003.24, the files are moved to the |
-hold No/Yes | This tells |
-testMail emailAddress | If set, all To, CC, and BCC values are set to this email address. This allows you to redirect all mail to yourself when testing your DocOrigin-powered solution. This can be easier than modifying the data stream for testing. |
-trace filename | If set, additional trace information will be stored in the named file. If the filename is omitted, a Trace.txt file will be created in the same folder as the |
See Also
