Mail Library
Contents
This library contains functions that are used for sending emails.
Usage
Add the following to your build.gradle
file:
dependencies {
include "com.enonic.xp:lib-mail:${xpVersion}"
}
In your JavaScript controller, add a require statement:
const mailLib = require('/lib/xp/mail');
You are now ready to use the library functionality.
You also need to configure your smtp-server before you can send out email. For details, see the configuration page |
Functions
send
This function 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 to
, cc
and bcc
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 |
E-mail address and optionally name of 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 |
Optional alternative e-mail address 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 |
string |
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
var flag1 = mailLib.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"'
});
var flag2 = mailLib.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
This function returns the default from email address configured in the XP mail configuration.
Example
var defaultFromEmail = mailLib.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 |
* |
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. |