Docs Developer Site
Developer Docs Code Stable Libraries Lib Mail

Mail library

Contents

This API provides functions that are used for sending emails.

Usage

Add the following to your build.gradle file:

dependencies {
  include xplibs.mail
}

Add the import statement to your code:

import mailLib from '/lib/xp/mail';

You are now ready to use the API.

You also need to configure your smtp-server before you can send out email. For details, see the configuration page

Functions

send

Sends an email message using the mail server configured.

The address values can be either a simple email address (e.g. name@domain.org ) or an address with a display name. In the latter case the email will be enclosed with angle brackets (e.g. Some Name <name@domain.org>).

The from parameter supports the default from email substitution. If the email address is not specified in angle brackets (e.g., Some Name <> or <>), the default from email address is used. However, an error is thrown if the default from email is not set.

The parameters from, to, cc, bcc and replyTo can be passed as a single string or as an array of strings, if there are multiple addresses to specify.

The content-type of the email can be specified by using the contentType parameter. See example below for sending a message with an HTML body.

Parameters

An object with the following parameters:

Name Kind Details

from

string | string[]

E-mail address(es) and optionally name(s) of the message sender

to

string | string[]

E-mail address(es) and optionally name(s) of the message’s recipient(s)

cc

string | string[]

Optional list of carbon copy e-mail address(es)

bcc

string | string[]

Optional list of blind carbon copy e-mail address(es)

replyTo

string | string[]

Optional alternative e-mail address(es) for replies

subject

string

Subject line of the message

body

string

Text content of the message

contentType

string

Optional content type of the message body

headers

object

Optional custom headers in the form of name-value pairs

attachments

Array

Optional attachments to include in the e-mail

Returns

boolean : true if message was successfully sent, false otherwise.

Example

Send a simple HTML e-mail
import {send} from '/lib/xp/mail';

const flag1 = send({
    from: 'me@enonic.com',
    to: 'user@somewhere.org',
    subject: 'HTML email test',
    body: '<h1>HTML Email!</h1><p>You can use the contentType parameter for HTML messages.</p>',
    contentType: 'text/html; charset="UTF-8"'
});
Send an e-mail with attachments
import {send} from '/lib/xp/mail';

const flag2 = send({
    from: 'Sales Department <sales@enonic.com>',
    to: 'user@somewhere.org',
    subject: 'Email Test from Enonic XP',
    cc: 'other@example.org',
    bcc: ['support@enonic.com', 'other@enonic.com'],
    replyTo: 'support@enonic.com',
    body: 'Welcome to Enonic XP!' + '\r\n\r\n' + '- The Dev Team',
    headers: {
        'Disposition-Notification-To': 'me@enonic.com'
    },
    attachments: [
        {
            fileName: 'logo.png',
            mimeType: 'image/png',
            data: stream1,
            headers: {
                'Content-ID': 'logo-img'
            }
        },
        {
            fileName: 'text.txt',
            data: stream2
        }
    ]
});

getDefaultFromEmail

Returns the default from email address configured in the XP mail configuration.

Example

Get a defaultFromEmail
import {getDefaultFromEmail} from '/lib/xp/mail';

const defaultFromEmail = getDefaultFromEmail();

Objects

attachments

Array of attachments to include in an e-mail

Properties of each element in the array

Name Kind Details

fileName

string

Attachment file name

data

ByteSource

Attachment stream

mimeType

string

Optional specification of attachment content type. If not specified, it will be inferred from the filename.

headers

object

Optional attachment headers in the form of name-value pairs.

Contents

Contents