Documentation Comments
Use this form to comment on this topic. You can also provide any general observations about the Online Documentation, or request that additional information be added in a future release.
Reality V15.2 Online Documentation (MoTW) Revision 3
EM_ADD_DELIVERY_DETAILS Function (DataBasic Email API) (em_add_delivery_details.htm)
Adds the delivery details to the started email, including the email addresses of the sender and at least one recipient. If a predefined delivery 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.
EM_ADD_DELIVERY_DETAILS([delivery-item || delivery-configuration])
delivery-itemThe item ID of a predefined delivery configuration item from an email configuration file (either the default EM_CONFIG file or a file previously specified by the EM_DEFINE_CONFIG function).
delivery-configurationA dynamic array of the parameters defining the delivery information for the email, as shown in the table below.
Each email address can optionally include the name of the sender or recipient (as appropriate) to be displayed by the receiving client. This display name can be omitted, in which case the email address does not need to be enclosed in the angled brackets (<>). Valid examples include:
User Name <username@example.com>
<username@example.com>
username@example.com
|
Attribute |
Name |
Description |
|---|---|---|
|
1 |
DESC |
An optional description of the configuration used or the name of the entry stored in the configuration file if no other attributes are passed. |
|
2 |
SUBJECT |
The text to appear as the emails subject. |
|
3 |
TO |
An optional value-mark delimited list of name and email addresses of the recipients. Although TO, CC and BCC are all optional, at least one must be defined. |
|
4 |
FROM |
The name and email address of the sender. |
|
5 |
CC |
An optional value-mark delimited list of the names and email address of the recipients to be copied into the email. |
|
6 |
BCC |
An optional value-mark delimited list of the names and email address of the recipients to be blind copied into the email. |
Note When emails are sent by the email server, all are addressed as To:. However, the email client differentiates between To: and Cc: from the labelling in the body of the email. When an address is Bcc:, the email server sends a copy to each address on the Bcc list individually but the labelling of To: and Cc: in the body of the email remains so that the email client can again differentiate the addresses. This ensures that no one knows others in the Bcc list and the Bcc individual sees a list of To: and Cc: recipients. The use of Bcc: adds overhead as the email has to be sent to each in the Bcc list separately. For example: sending an email To: one person and Cc: to 10 others will result in one email being sent. However, if five people are added in as Bcc recipients, the email is now sent six times (once for the To: and Cc: people and five times, one for each of the Bcc people).
EM_ADD_DELIVERY_DETAILS 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.
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.