ballerina/email

Package Overview

This package contains functions to perform email operations such as sending and reading emails using the SMTP, POP3, and IMAP4 protocols.

Client

This package supports the following three client types.

  • email:SmtpClient - The client, which supports sending an email using the SMTP protocol.
  • email:PopClient - The client, which supports receiving an email using the POP3 protocol.
  • email:ImapClient - The client, which supports receiving an email using the IMAP4 protocol.

SMTP Client

To send an email using the SMTP protocol, you must first create an email:SmtpClient object. The code for creating an email:SmtpClient can be found below.

Creating a client

The following code creates an SMTP client, which connects to the default port(465) and enables SSL.

1email:SmtpClient smtpClient = new ("smtp.email.com",
2 "sender@email.com",
3 "pass123");

The port number of the server can be configured by passing the following configurations.

1email:SmtpConfiguration smtpConfig = {
2 port: 465 // Can use ports, 465, 587 or 25
3};
4
5email:SmtpClient smtpClient = new ("smtp.email.com",
6 "sender@email.com",
7 "pass123",
8 smtpConfig);
Sending an email

Once the email:SmtpClient is created, an email can be sent using the SMTP protocol through that client. Samples for this operation can be found below.

1email:Message email = {
2 to: ["receiver1@email.com", "receiver2@email.com"],
3 cc: ["receiver3@email.com", "receiver4@email.com"],
4 bcc: ["receiver5@email.com"],
5 subject: "Sample Email",
6 body: "This is a sample email.",
7 'from: "author@email.com",
8 sender: "sender@email.com",
9 replyTo: ["replyTo1@email.com", "replyTo2@email.com"]
10};
11
12email:Error? response = smtpClient->sendMessage(email);

An email can be sent directly by calling the client, specifying optional parameters as named parameters, as well. Samples for this operation can be found below.

1email:Error? response = smtpClient->send(
2 ["receiver1@email.com", "receiver2@email.com"],
3 "Sample Email",
4 "author@email.com",
5 body="This is a sample email.",
6 cc=["receiver3@email.com", "receiver4@email.com"],
7 bcc=["receiver5@email.com"],
8 sender="sender@email.com",
9 replyTo=["replyTo1@email.com", "replyTo2@email.com"]
10);

POP3 Client

To receive an email using the POP3 protocol, you must first create an email:PopClient object. The code for creating an email:PopClient can be found below.

Creating a client

The following code creates a POP3 client, which connects to the default port(995) and enables SSL.

1email:PopClient|email:Error popClient = new ("pop.email.com",
2 "reader@email.com",
3 "pass456");

The port number of the server can be configured by passing the following configurations.

1email:PopConfiguration popConfig = {
2 port: 995
3};
4
5email:PopClient|email:Error popClient = new ("pop.email.com",
6 "reader@email.com",
7 "pass456",
8 popConfig);
Receiving an email

Once the email:PopClient is created, emails can be received using the POP3 protocol through that client. Samples for this operation can be found below.

1email:Message|email:Error? emailResponse = popClient->receiveMessage();

IMAP4 Client

To receive an email using the IMAP4 protocol, you must first create an email:ImapClient object. The code for creating an email:ImapClient can be found below.

Creating a client

The following code creates an IMAP4 client, which connects to the default port(993) and enables SSL.

1email:ImapClient|email:Error imapClient = new ("imap.email.com",
2 "reader@email.com",
3 "pass456");

The port number of the server and/or the SSL support can also be configured by passing the following configurations.

1email:ImapConfiguration imapConfig = {
2 port: 993,
3 enableSsl: true
4};
5
6email:ImapClient|email:Error imapClient = new ("imap.email.com",
7 "reader@email.com",
8 "pass456",
9 imapConfig);
Receiving an email

Once the email:ImapClient is created, emails can be received using the IMAP4 protocol through that client. Samples for this operation can be found below.

1email:Message|email:Error emailResponse = imapClient->receiveMessage();

POP3 and IMAP Listeners

As POP3 and IMAP4 protocols are similar in the listener use cases, lets consider POP3. In order to receive emails one-by-one from a POP3 server, you must first create an email:PopListener object. The code for creating an email:PopListener can be found below.

1listener email:PopListener emailListener = check new ({
2 host: "pop.email.com",
3 username: "reader@email.com",
4 password: "pass456",
5 pollingInterval: 2,
6 port: 995
7});

Once initialized a service can listen to the new emails as follows. New emails get received at the onMessage method and when errors happen onError method get called.

1service "emailObserver" on emailListener {
2
3 remote function onMessage(email:Message emailMessage) {
4 io:println("Email Subject: ", emailMessage.subject);
5 io:println("Email Body: ", emailMessage.body);
6 }
7
8 remote function onError(email:Error emailError) {
9 io:println("Error while polling for the emails: " + emailError.message());
10 }
11
12}

For information on the operations, which you can perform with this package, see the Functions below. For examples of the usage of the operation, see the following.

Clients

[3]

ImapClient

Represents an IMAP Client, which interacts with an IMAP Server.

PopClient

Represents a POP Client, which interacts with a POP Server.

SmtpClient

Represents an SMTP Client, which interacts with an SMTP Server.

Classes

[2]

ImapListener

Represents a service listener that monitors the email server location.

PopListener

Represents a service listener that monitors the email server location.

Records

[9]

Attachment

Email attachment.

ImapConfiguration

Configuration of the IMAP Endpoint.

ImapListenerConfiguration

Configuration for Email listener endpoint.

Message

Email message properties.

Options

Optional parameters for an Email message.

PopConfiguration

Configuration of the POP Endpoint.

PopListenerConfiguration

Configuration for Email listener endpoint.

SecureSocket

Secure Socket configuration.

SmtpConfiguration

Configuration of the SMTP Endpoint.

Constants

[1]

DEFAULT_FOLDER

Default folder to read emails.

Enums

[2]

Protocol

Represents protocol options.

Security

Security type.

Errors

[1]

Error

Defines the common error type for the module