EM_START_EMAIL Function
Purpose
Defines the start of an email by defining the connection information for the mail server to be used. If a predefined host configuration item is specified the details are loaded from that item; these details can be overridden by providing additional configuration parameters.
Returns TRUE or FALSE.
Syntax
EM_START_EMAIL(host-item, host-configuration)
Syntax elements
host-item The item ID of a predefined host configuration item from an email configuration file (either the default EM_CONFIG file or a file previously specified by the EM_DEFINE_CONFIG function) to be used as the basis for the mail server connection. If this is not set, an empty configuration item is created ready to be overwritten by the configuration defined by the host-configuration parameter.
host-configuration A dynamic array of the parameters defining the mail server connection configuration. This overrides any values that may have been loaded from an existing predefined configuration item specified by host-item.
|
Attribute |
Name |
Description |
||
|---|---|---|---|---|
|
1 |
DESCRIPTION |
Optional description of configuration for reference only. |
||
|
2 |
CONFIG |
Optional configuration table. |
||
|
Value |
Name |
Description |
||
|
1 |
RETRY LIMIT |
Maximum number of times to retry receiving a response from the server. Setting the number of retries to -1 will retry forever whereas setting to zero will not retry after the initial attempt. If this is left blank, the default of 10 retries is used. |
||
|
2 |
RETRY SLEEP |
The time in seconds (between 1 and 10) to sleep before the first attempt to receive a message and subsequent retries). If this is left blank, the default value of 1 second is used. |
||
|
3 |
CONNECTION |
The information required to set up communications with the server. | ||
|
Value |
Name |
Description |
||
|
1 |
HOST |
The fully-qualified name or IP address of the mail server to use. |
||
|
2 |
PORT |
The port used for connecting to the mail server. If this is left blank, the default of 25 is used. |
||
|
3 |
PROTOCOL |
The protocol used for connecting to the mail server. Currently, the only valid option is TCP. If this is left blank, the default value TCP is used. |
||
|
4 |
TLS |
The setting for the TLS (transport layer security) option. If this is set, Currently, the only valid options are none and server. If neither option is set, the TLS string is not added to the connection. |
||
|
4 |
AUTH DETAILS |
Optional authentication details for logging into the mail server. |
||
|
Value |
Name |
Description |
||
|
1 |
USER |
The name of the user account with which to login to the mail server. If this is not set (null), no authentication is used. |
||
|
2 |
PASSWORD |
The password of the user account. If no user account is defined, the password is ignored. |
||
Returns
EM_START_EMAIL returns TRUE if successful or FALSE if unsuccessful. If FALSE, the details of the failure to load the configuration can be found by inspecting the error number held in the common variable EM_ERROR_DETAILS.
Comments
You must include the item #EM_INCLUDES in all programs that use the Email API functions; for example, you could add the line
INCLUDE #EM_INCLUDES FROM /SYSFILES/SYS.BASLIB
at the start of the program, or create an item to be automatically included that contains this line.