Updated January 2024; see History
The EMAILX configuration file provides a means of setting default parameters and other options in one place rather than having to set them redundantly across many programs in an application, department or site. The file is normally called emailx.cfg, although there is no default name or search path; you must specify it explicitly in the cfgfile parameter. It consists of directives in the form:
<item> = <value> ; <optional comment>
Items which correspond directly to actual EMAILX parameters, such as PASSWORD, will be overridden by a non-blank value passed in the corresponding parameter in the XCALL statement. Other items, such as LOGLVL, control extensions not otherwise configurable via the parameter list.
Note that while the format is generally typical of other configuration files, it doesn't completely conform to the INI standard required by INIX.SBX, due to the lack of [sections] and the looser use of spaces and comments.
Note also that the config file items are case INsensitive.
Item |
Value / Description |
|---|---|
ADDBCC |
Any number of ADDBCC directives may be specified, each with a single unadorned email address, for example "ADDBCC=eavesdropper@bigbrother.com." |
SMTP Authentication. |
|
CONNLOCK |
The only option is 1 (CONNLOCK=1), which uses a system lock to limit usage to only one SMTP session—i.e. to prevent multiple users from making simultaneous connections to the SMTP server. Typically unnecessary. |
DOMAIN |
DOMAIN is a strictly optional directive which specifies the domain to be added to any unqualified address, thus allowing you to abbreviate the addresses, say, for your local company by dropping the @ and everything after it. For example, if DOMAIN=microsabio.com, then if you specify the address "admin" in the to or from fields, it will automatically be expanded to "admin@microsabio.com". |
HOST |
HOST fulfills the same purpose here as it does in the subroutine parameter list, and is used only if HOST is blank or not specified in the subroutine. This is typically your domain name, and is used to identify your computer or domain to the SMTP server when making the initial connection. Theoretically, the SMTP server may decide to accept or reject you based on whether it recognizes or can resolve this domain name. |
Log file name |
|
Log level |
|
Password. |
|
REDIRECT |
REDIRECT provides an easy way to temporarily redirect ALL outgoing mail to a specified address for testing purposes. Note that the original To, CC, and BCC addresses will remain in the header, but will all be changed to the redirect address for actual routing purposes. For example: REDIRECT = me@mydomain.com |
REPLYTO |
This is an important directive often confused with the return address. This is where mail will be sent if the reader clicks the "Reply" button in their email client. It may or may not be the same as the address of the person (or cyber-entity) that actually sent the message. If specified, it inserts a line in the message header reading "Reply-To: " followed by the specified address. |
RTNADDR |
Default return address; used only if the from parameter is empty. May be unadorned, i.e. name@domain, or adorned with a descriptive prefix, e.g. Mr. Magoo <magoo@cartoons. tv>. See History below. Also see REPLYTO above. |
Enable/Disable secure EHLO message. |
|
Type of secure connection. |
|
SMTP server name |
|
Signature file |
|
USERNAME |
USERNAME fulfills the same purpose here as it does in the subroutine parameter list, and is used only if the AUTH directive is specified, and the username is blank or not specified in the subroutine. |
Maximum wait for SMTP response |
|
WAIT2 |
Similar to WAIT, but units are milliseconds (default=200) rather than seconds, and applies only to packets received after the first response to the HELO/EHLO command. Normally, once the first packet of a response to a command is received, any additional packets are received without delay. But in the case of HELO/EHLO, the server typically responds with an extended list of supported options, sometimes with small delays between them. |
Sample
;EMAILX.SBX configuration file
WAIT = 10 ; max wait (secs) for SMTP response
SERVER = localhost ; SMTP server
SECURE = STARTTLS ; use STARTTLS protocol
AUTH = * ; SMTP auth mode (LOGIN or PLAIN)
USERNAME = yo@micasa.com ; SMTP login username
PASSWORD = secret ; SMTP login password
HOST = microsabio.com ; HELO (sending domain)
DOMAIN = microsabio.com ; default domain to add to unqualified addrs
RTNADDR = ashell@microsabio.com ; return address (default FROM address)
REPLYTO = replyto@microsabio.com ; default Reply-To address
SIGNATURE = EMAILX.SIG ; signature file (text, amos or native spec)
LOGFILE = EMAILX.LOG ; log file name (amos or native)
LOGLVL = 3 ;
History
2024 February, A-Shell 6.5.1755, EMAILX.SBX(147) and (148): The RTNADDR directive and from parameters can now include descriptive names, such as Big Brother <bigbro@us.gov> instead of just bigbro@us.gov. Also, a descriptive name included in the from parameter or RTNADDR configuration file directive will now appear in the header seen by the recipient, if no explicit "From:" clause is included in the header parameter. Previously, if not specified explicitly, the recipient would see only the unadorned version of the from address, e.g. name@domain.
2023 June, A-Shell 6.5.1732, EMAILX.SBX(144): Support multiple ADDBCC directives.
2018 December, A-Shell 6.5.1651, EMAILX.SBX(139): Add parameters ADDBCC and REDIRECT.
