Mail API
Contents
This API provides functions that are used for sending emails.
Usage
Add the following to your build.gradle file:
dependencies {
include "com.enonic.xp:lib-mail:${xpVersion}"
}Add the import statement to your controller:
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 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
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"'
});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
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 |
* |
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. |