Triggers

The ballerina/email connector supports event-driven email processing through IMAP and POP3 listeners. The listeners poll the mail server at configurable intervals and invoke your service callbacks when new emails arrive, errors occur, or the connection closes.

Three components work together:

Component	Role
email:ImapListener	Polls an IMAP server at a configurable interval and dispatches new emails to the attached service.
email:PopListener	Polls a POP3 server at a configurable interval and dispatches new emails to the attached service.
email:Service	Defines the onMessage, onError, and onClose callbacks invoked by the listener.
email:Message	The email message payload passed to the onMessage callback.

For action-based operations, see the Action Reference.

---

Listener

The email listeners (email:ImapListener and email:PopListener) establish the connection and manage event subscriptions.

Configuration

The listener supports the following connection strategies:

Config Type	Description
ImapListenerConfiguration	Configuration for the IMAP listener that polls for new emails.
PopListenerConfiguration	Configuration for the POP3 listener that polls for new emails.

ImapListenerConfiguration fields:

Field	Type	Default	Description
host	string	Required	Host address of the IMAP server.
username	string	Required	Username for IMAP authentication.
password	string	Required	Password for IMAP authentication.
pollingInterval	decimal	30	Time interval in seconds between email polling attempts.
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.

PopListenerConfiguration fields:

Field	Type	Default	Description
host	string	Required	Host address of the POP3 server.
username	string	Required	Username for POP3 authentication.
password	string	Required	Password for POP3 authentication.
pollingInterval	decimal	30	Time interval in seconds between email polling attempts.
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 listener

Using an IMAP listener:

import ballerina/email;

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

listener email:ImapListener imapListener = check new ({
    host: imapHost,
    username: username,
    password: password,
    pollingInterval: 10
});

Using a POP3 listener:

import ballerina/email;

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

listener email:PopListener popListener = check new ({
    host: popHost,
    username: username,
    password: password,
    pollingInterval: 10
});

---

Service

An email:Service is a Ballerina service attached to an email:ImapListener or email:PopListener. It implements callbacks that are invoked when new emails arrive, errors occur, or the listener connection closes.

Callback signatures

Function	Signature	Description
onMessage	remote function onMessage(email:Message emailMessage)	Invoked when a new email is received. This callback is mandatory.
onError	remote function onError(email:Error emailError)	Invoked when an error occurs during email polling. Optional.
onClose	remote function onClose(email:Error? closeError)	Invoked when the listener connection is closed. Optional.

note

You must implement the onMessage callback. The onError and onClose callbacks are optional: implement only the ones relevant to your use case.

Full usage example

import ballerina/email;
import ballerina/log;

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

listener email:ImapListener imapListener = check new ({
    host: imapHost,
    username: username,
    password: password,
    pollingInterval: 10
});

service "emailObserver" on imapListener {
    remote function onMessage(email:Message emailMessage) {
        log:printInfo("New email received",
            subject = emailMessage.subject,
            'from = emailMessage.'from,
            to = emailMessage.to
        );
    }

    remote function onError(email:Error emailError) {
        log:printError("Error while polling for emails",
            'error = emailError
        );
    }

    remote function onClose(email:Error? closeError) {
        log:printInfo("Listener connection closed");
    }
}

note

Both email:ImapListener and email:PopListener use the same service callback interface. You can switch between IMAP and POP3 by changing only the listener type and configuration.

---

Supporting types

Message

Field	Type	Description
to	string|string[]	Recipient email address(es).
subject	string	Subject of the email.
'from	string?	Sender's email address.
body	string?	Plain text body of the email.
htmlBody	string?	HTML body of the email.
cc	string|string[]?	CC recipient address(es).
bcc	string|string[]?	BCC recipient address(es).
replyTo	string|string[]?	Reply-To address(es).
contentType	string?	Content type of the email body (e.g., "text/plain").
headers	map<string>?	Custom email headers as key-value pairs.
sender	string?	Sender address (may differ from from).
attachments	mime:Entity|Attachment|(mime:Entity|Attachment)[]?	Email attachments as file references or MIME entities.

Attachment

Field	Type	Description
filePath	string	File path of the attachment.
contentType	string	MIME content type of the attachment (e.g., "application/pdf").