DataBasic Email API

Overview

The DataBasic Email API Application Programming Interface - a set of functions that you can use in your programs to work with a component.  provides a mechanism that allows emails with attachments to be sent from within DataBasic.

It consists of the following discrete actions:

1. Specifying the configuration file (optional)

   This specifies a configuration file to be used to retrieve predefined host and delivery configurations. If not specified, a default file is assumed.

2. Starting the email

   This constructs the template for the email and sets the host details for the communications with the SMTP server, either defined at run-time or from a host configuration item in the specified configuration file.

3. Addressing the email

   This handles the delivery options for the email such as Subject, To, From, Cc and Bcc. Again, this is either defined at run-time or from a delivery configuration item in the specified configuration file.

4. Adding content

   The body of the email needs to be populated with plain text content and, optionally, HTML content. Plain text is required for email clients that cannot display HTML. HTML content not only permits richer formatting but also allows links to attached content to be displayed in-line.

5. Adding attachments

   Adding external content to an email is handled as attachments. These attachments appear either as files that can be downloaded from the email or as content that is embedded in the email, such as images.

6. Sending the email

   All of the elements of the email are combined to produce the finished item. The email is then sent by communicating with the specified mail server.

An example program is provided in the Online Documentation.

Summary of functions

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.

• EM_DEFINE_CONFIG

  Optionally specifies an email configuration file that contains any predefined configuration items. This can be unique to the current account, or a Q-pointer to allow for a global configuration.

  The default email configuration file (which is assumed if no alternative file is specified by this function) is EM_CONFIG in the account from which the DataBasic Email API is being called.

• EM_START_EMAIL

  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.

• EM_ADD_AUTH_DETAILS

  Adds authentication details to an existing connection.

• EM_ADD_DELIVERY_DETAILS

  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.

• EM_ADD_ATTACHMENT

  Adds an attachment to the email from the supplied content. The size of the attachment is limited by the size of the memory available to the user.

• EM_ADD_ATTACHMENT_ITEM

  Adds an attachment to the email from the supplied file and item. The size of the attachment is limited by the size of the memory available to the user.

• EM_ADD_HTML_TEXT

  Adds an HTML-formatted fragment to appear in the body of the email. This is displayed only if the client receiving the email can display HTML.

• EM_ADD_PLAIN_TEXT

  Adds a plain text version of the email to the body of the email. This is displayed if the client receiving the email cannot display HTML or if an HTML version is not supplied by EM_ADD_HTML_TEXT.

• EM_SEND_EMAIL

  Sends the email that has been constructed using the defined connection information.

• EM_ENABLE_DEBUG

  Enables the printing of debugging information including the encoded content when the email is sent.

Predefined host and delivery configurations (email configuration files)

To make their programs independent of the mail server configuration and delivery details, DataBasic programmers can make of use predefined configuration items that define the host connection details and delivery options (such as the sender and recipients).

These host and delivery configuration items are defined in the email configuration files. The default email configuration file, which is assumed if no alternative file is specified by the EM_DEFINE_CONFIG function, is EM_CONFIG in the account from which the DataBasic Email API is being called.

Host configuration items

The host configuration item IDs are prefixed with by EH_ and comprise the connection information for the host email server.

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, ;TLS=option is added to the details used for the connection. 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.

Delivery configuration items

The delivery configuration item IDs are prefixed by ED_ and comprise the delivery information for the email.

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.

Error handling

Some DataBasic Email API functions return TRUE if successful or FALSE if unsuccessful.

Each function that returns FALSE returns details of the error in the named common EM_COMMON variable EM_ERROR_DETAILS. The format of this variable is compatible with the DataBasic PRINTERR statement:

Attribute	Description
1	Error number.
2	Supporting information for the error number.

If an exception handler has been defined in the user's program, each function that would otherwise return FALSE instead throws an exception. The details of the error condition are available to the exception handler using the DataBasic Exception Handler functions EXCEPT_NUM() and EXCEPT_MSG() to retrieve the contents of EM_ERROR_DETAILS<1> and EM_ERROR_DETAILS<2> respectively.

The following table summarises the specific error numbers and supporting information applicable to each function.

Function	Error number	Supporting information
EM_DEFINE_CONFIG	201	Value of missing item ID.
EM_START_EMAIL	201	The filename that could not be opened to read the configuration item.
	202	The item ID of the configuration item that could not be read.
	1352	The invalid port number used.
	4257	The protocol that was not recognised.
EM_ADD_DELIVERY_DETAILS	201	The Reality file that could not be opened to read the configuration item.
	202	The item ID of the configuration item that could not be read.
	552	The email address that is incorrectly formatted. (From:) if the From address is missing. (Recipients:) if no recipients are supplied.
EM_ADD_ATTACHMENT	200	Empty to show no filename was supplied for the attachment.
	552	alt to indicate that the ALT TEXT parameter was not supplied.
	1939	The value of the incorrectly-supplied attachment type.
EM_ADD_ATTACHMENT_ITEM	200	Empty to show no filename was supplied for the attachment.
	201	The Reality file that could not be opened to read the item from.
	202	The item ID of the Reality item that could not be read to attach.
	552	alt to indicate that the ALT TEXT parameter was not supplied.
	1939	The value of the incorrectly-supplied attachment type.
EM_ADD_HTML_TEXT	None	N/A
EM_ADD_PLAIN_TEXT	None	N/A
EM_SEND_EMAIL	4096	The message string, from the email server, that did not match the expected response.
	Various	The connection string that failed to connect to the server. The message string that was received as an error. If failing to send a message there is no supporting information. However, using EM_ENABLE_DEBUG will show a trace of the messages being sent and received (see IPC Error Codes for a list of possible networks).
EM_ENABLE_DEBUG	None	N/A