Main Page » Mail Functions

Mail Functions

This module contains functions for sending e-mail from XQuery. It is based on the Apache Commons Email library. A single map value carries both the SMTP connection settings and the message contents.

Conventions

The module must be installed in the repository before it can be used. Pre-built module jars are available (via files.basex.org):

REPO INSTALL https://files.basex.org/modules/org/basex/modules/mail-12.3.jar

In order to use it, it needs to be imported in the header of the query:

import module namespace mail = 'http://basex.org/modules/mail';

All functions in this module are assigned to the http://basex.org/modules/mail namespace, which in the following is assumed to be bound to the mail prefix.

Errors raised by the underlying mail library surface as a QueryException whose message is prefixed with Mail:.

Functions

`mail:send`

Signature

mail:send(
  $options  as map(*)
) as empty-sequence()

Summary

Sends an e-mail. The $options map carries both the SMTP connection settings and the message contents. The following keys are recognized:

Key	Type	Description
`subject`	`xs:string`	Subject line.
`from`	`xs:string`	Sender address.
`to`	`xs:string*`	Recipient addresses.
`cc`	`xs:string*`	CC recipients.
`bcc`	`xs:string*`	BCC recipients.
`reply-to`	`xs:string*`	Reply-to addresses.
`host`	`xs:string`	SMTP host.
`port`	`xs:integer`	SMTP port.
`ssl`	`xs:boolean`	Use SSL on connect.
`tls`	`xs:boolean`	Start TLS.
`user`	`xs:string`	SMTP user name.
`password`	`xs:string`	SMTP password.
`message`	`xs:string`	Message body.
`attachment`	`xs:string*`	Filesystem paths of files to attach.

The message body is encoded as UTF-8. Each address and attachment value is trimmed before use. SMTP authentication is performed when both user and password are supplied.

Examples

import module namespace mail = 'http://basex.org/modules/mail';

mail:send({
  'host': 'smtp.your-mail-provider.org',
  'ssl': true(),
  'user': 'from@your-mail-provider.org',
  'password': '...',
  'from': 'from@your-mail-provider.org',
  'to': 'to@your-mail-recipient.org',
  'subject': 'Subject',
  'message': 'Message'
})

Sends a plain-text e-mail via an authenticated SMTP server.

⚡Generated with XQuery