Actions

The ballerina/email package exposes the following clients:

Client	Purpose
SMTP Client	Sends emails via SMTP with support for text/HTML bodies, attachments, and custom headers.
IMAP Client	Receives emails from an IMAP server with configurable folder and timeout.
POP Client	Receives emails from a POP3 server with configurable folder and timeout.

For event-driven integration, see the Trigger Reference.

---

SMTP client

Sends emails via SMTP with support for text/HTML bodies, attachments, and custom headers.

Configuration

Field	Type	Default	Description
host	string	Required	Host address of the SMTP server (e.g., smtp.gmail.com).
username	string?	()	Username for SMTP authentication.
password	string?	()	Password for SMTP authentication.
port	int	465	Port number of the SMTP server.
security	Security	SSL	Type of security channel (SSL, START_TLS_AUTO, START_TLS_ALWAYS, or START_TLS_NEVER).
secureSocket	SecureSocket	()	SSL/TLS secure socket configuration.

Initializing the client

import ballerina/email;

configurable string senderAddress = ?;
configurable string senderPassword = ?;

email:SmtpClient smtpClient = check new ("smtp.gmail.com", senderAddress, senderPassword);

Operations

Send operations

sendMessage

Sends an email using a structured Message record.

Parameters:

Name	Type	Required	Description
email	Message	Yes	The email message record containing to, subject, body, and other fields.

Returns: Error?

note

If contentType is set in the Message record, it must be a text/* MIME type (e.g., "text/plain", "text/html"). Non-text content types will return an email:Error at runtime.

Sample code:

email:Message emailMessage = {
    to: "[email protected]",
    subject: "Sample Email Title",
    body: "This is a sample email text body."
};
check smtpClient->sendMessage(emailMessage);

send

Sends an email using individual parameters for convenience.

Parameters:

Name	Type	Required	Description
to	string|string[]	Yes	Recipient email address(es).
subject	string	Yes	Subject of the email.
'from	string	Yes	Sender's email address.
body	string	Yes	Text body of the email.
htmlBody	string	No	HTML body of the email.
cc	string|string[]	No	CC recipient address(es).
bcc	string|string[]	No	BCC recipient address(es).
replyTo	string|string[]	No	Reply-To address(es).
sender	string	No	Sender address (if different from from).
contentType	string	No	Content type of the body.
headers	map<string>	No	Custom email headers.
attachments	mime:Entity|Attachment|(mime:Entity|Attachment)[]	No	File attachments.

Returns: Error?

Sample code:

check smtpClient->send(
    "[email protected]",
    "Meeting Reminder",
    "[email protected]",
    "Don't forget about our meeting tomorrow at 10 AM.",
    cc = "[email protected]"
);

---

IMAP client

Receives emails from an IMAP server with configurable folder and timeout.

Configuration

Field	Type	Default	Description
host	string	Required	Host address of the IMAP server (e.g., imap.gmail.com).
username	string	Required	Username for IMAP authentication.
password	string	Required	Password for IMAP authentication.
port	int	993	Port number of the IMAP server.
security	Security	SSL	Type of security channel (SSL, START_TLS_AUTO, START_TLS_ALWAYS, or START_TLS_NEVER).
secureSocket	SecureSocket	()	SSL/TLS secure socket configuration.

Initializing the client

import ballerina/email;

configurable string imapHost = ?;
configurable string username = ?;
configurable string password = ?;

email:ImapClient imapClient = check new (imapHost, username, password);

Operations

Receive operations

receiveMessage

Reads an email message from the specified folder. Returns () if no unread emails are available.

Parameters:

Name	Type	Required	Description
folder	string	No	Mailbox folder to read from (default: "INBOX").
timeout	decimal	No	Timeout in seconds to wait for an email (default: 30).

Returns: Message|Error?

Sample code:

email:Message? message = check imapClient->receiveMessage();

Sample response:

{"to": "[email protected]", "subject": "Hello", "from": "[email protected]", "body": "Hi there, this is a test email.", "contentType": "text/plain"}

close

Closes the IMAP client connection and releases resources.

Returns: Error?

Sample code:

check imapClient->close();

---

POP client

Receives emails from a POP3 server with configurable folder and timeout.

Configuration

Field	Type	Default	Description
host	string	Required	Host address of the POP3 server (e.g., pop.gmail.com).
username	string	Required	Username for POP3 authentication.
password	string	Required	Password for POP3 authentication.
port	int	995	Port number of the POP3 server.
security	Security	SSL	Type of security channel (SSL, START_TLS_AUTO, START_TLS_ALWAYS, or START_TLS_NEVER).
secureSocket	SecureSocket	()	SSL/TLS secure socket configuration.

Initializing the client

import ballerina/email;

configurable string popHost = ?;
configurable string username = ?;
configurable string password = ?;

email:PopClient popClient = check new (popHost, username, password);

Operations

Receive operations

receiveMessage

Reads an email message from the specified folder. Returns () if no unread emails are available.

Parameters:

Name	Type	Required	Description
folder	string	No	Mailbox folder to read from (default: "INBOX").
timeout	decimal	No	Timeout in seconds to wait for an email (default: 30).

Returns: Message|Error?

Sample code:

email:Message? message = check popClient->receiveMessage();

Sample response:

{"to": "[email protected]", "subject": "Hello", "from": "[email protected]", "body": "Hi there, this is a test email.", "contentType": "text/plain"}

close

Closes the POP3 client connection and releases resources.

Returns: Error?

Sample code:

check popClient->close();