ajSendEmail function

Description

The ajSendEmail function sends an email to recipients with a given subject, message, and attachments.

Syntax

ajSendEmail(subject,message,to_address,[cc_address],[bcc_address],[attachment_path],[html_mail],[smtp_id],[host],[port],[username],[password],[sender_address],[run_condition],[run_by_function_point_only])

Argument Name	Argument Type	Description
subject (required)	String	The subject for the email.
message (required)	Range	The content of the email from a range of cells. The range of cells can span across multiple rows and columns. Each row represents a broken line and all the columns will be concatenated.
to_address (required)	Range	TO email address from a range of cells. The range of cells can span across multiple rows and columns. Each cell should contain one email address.
cc_address (optional)	Range	CC email address from a range of cells. The range of cells can span across multiple rows and columns. Each cell should contain one email address.
bcc_address (optional)	Range	BCC email address from a range of cells. The range of cells can span across multiple rows and columns. Each cell should contain one email address.
attachment_path (optional)	Range	The attachment file paths of the email from a range of cells. The range of cells can span across multiple rows and columns. Each cell contains one file path. The default value is an empty string (“”), which is no attachment.
html_mail (optional)	Boolean	If it equals FALSE, the function will process the Body as plain text. If it equals TRUE, the function will process the Body as HTML formatted. The default value is FALSE.
smtp_id (optional)	String	The SMTP Connection ID defined in worksheet ##ExternalResources. If it is omitted, parameter 'host','port', 'sender_address' become mandatory. If a 'smtp_id' is provided and 'host', 'port', 'username', 'password' or 'sender_address' are not empty, they will overwrite the configuration defined in smtp_id in ##ExternalResources.
host (optional)	String	The IP address or FQDN of the SMTP server.
port (optional)	String	The listening port of the email service of the SMTP server.
username (optional)	String	The email account login user name.
password (optional)	String	The password for the username.
sender_address (optional)	String	FROM email address.
run_condition (optional)	Boolean	The function will run when the value is TRUE. Otherwise will not run. The default value is TRUE.
run_by_function_point_only (optional)	Boolean	If it equals FALSE, the function can be executed through ‘Excel Calculation’ (can be either Automatic or Manual, Calculate Now or Calculate Sheet) or Preview Function Point. If it equals TRUE, the function can be executed with Preview Function Point (AlchemyJ ribbon \ Preview Function Point) only. The default value is TRUE.

The function will return:

1) Return Value: TRUE / #Value

2) Return Type: Single Value

Example

Firstly, setup the STMP Connection and use the STMP Connection ID as "primary". The mail server information could be setup in ##ExternalResources or input as function parameters.

This example sends an HTML email to an email address.

The result is TRUE which indicates the email has been sent out successfully. However, it does not necessarily mean the recipient can receive or has received the email. Whether a recipient receives the email depends on how the mail server handles the email. That is beyond the reach of this function.

It will return #VALUE! when there is an error in the usage of the function.

As Html_mail is TRUE and an email body is in HTML format, the mail client displays the content with HTML formatting.

Click here to download the use case workbooks for further reference.

Error Scenarios

It will return #VALUE! when missing any required parameter or mismatch parameter type. Besides, system will raise error for below scenario(s).

Error Scenario
Attachment path does not exist.
External Resources Worksheet does not exist.
Failed to send email.
Host or port has not been provided while not using the smtp_id to send email.
Invalid port.
Invalid SMTP connection id.
Message is empty.
Sender address is empty.
Subject is empty.
To address is empty.
Username is empty while the password is provided.