saxon:send-mail

Sends an email message.

send-mail($emailConfig as map(*), $subject as xs:string, $content as item()) ➔ xs:boolean

Arguments

 

$emailConfig

map(*)

The email configuration

 

$subject

xs:string

The subject/title of the email

 

$content

item()

The body of the email

Result

xs:boolean

send-mail($emailConfig as map(*), $subject as xs:string, $content as item(), $attachment as item()*) ➔ xs:boolean

Arguments

 

$emailConfig

map(*)

The email configuration

 

$subject

xs:string

The subject/title of the email

 

$content

item()

The body of the email

 

$attachment

item()*

Attachments to the email

Result

xs:boolean

Namespace

http://saxon.sf.net/

Saxon availability

Requires Saxon-PE or Saxon-EE. Implemented since Saxon 9.5. Available for Java only.

Notes on the Saxon implementation

This extension function is not available on SaxonCS or SaxonC.

Use of this function requires the JavaMail API. The mail.jar must be available on the classpath. From Saxon 9.9, the required jar is compiled against version 1.6 (previously, this was version 1.4). The jar is not redistributed as part of the Saxon product, but is available for download from the JavaMail project on GitHub.

From 9.9, the email configuration option ssl is introduced.

From 9.8.0.5, the function was upgraded: for details of the changes, see bug 3400. This documentation describes the latest version.

Details

This function takes four arguments:

  1. $emailConfig is a map, which contains configuration options required to send an email. The following key-value pairs are accepted:

    Name Type Required? Description
    smtp-server xs:string yes The mail transfer agent will use the SMTP server specified here by the user to send the email message
    port xs:integer no The port number used by the SMTP server (default 25)
    to xs:string* yes Email addresses of recipients
    cc xs:string* no Email addresses of cc recipients
    bcc xs:string* no Email addresses of bcc recipients
    username xs:string no The username used for authentication with the email server
    password xs:string no The password used for authentication with the email server
    from xs:string no The email address of the sender
    realname xs:string no The personal name of the sender of the email
    html xs:boolean no Indicates whether the email body content should be serialized as HTML or as plain text. The default is false()
    ssl xs:boolean no Indicates whether to access mail servers over connections secured using SSL or TLS. This option was introduced in Saxon 9.9.0.1. The default is false(). Please ensure that the required smtp-server name and port number has also been provided for use with the secure connection as specified by the host server.

    Generally the "option parameter conventions" apply, as defined section 1.5 of the W3C Functions and Operators specification. However, for backwards compatibility reasons, parameters expecting a boolean or an integer can be supplied as a string that is castable to the required boolean or integer.

    In addition to the above options, any string-valued parameter whose name begins with "mail." is passed unchanged as a property to the Java mail API. The value can be any atomic value: it will be converted to a string. For example, the option mail.smtp.timeout can be set, as an integer, or mail.debug can be set, as a boolean. Similarly, options can be set to select an SSL transport. Any option values supplied in this form take precedence over the Saxon-defined options listed above.

    Email addresses appearing in the to, cc, and bcc lists may use the syntax John Smith <john.smith@example.com>

  2. $subject (xs:string) is the subject or title of the message. This is a string which the recipient of the email will typically see first, and provides a summary of the email content.

  3. $content (either xs:string or element(html)) is an item which makes up the content of the email to be sent. This value presents the content as either plain text or html. Anything else is serialized as plain text.

  4. $attachment is a sequence of items. This argument accepts a list of files to be attached to the email. The argument is optional - omitting it is equivalent to supplying an empty sequence, i.e. no attachments.

The function returns a boolean: true indicates email successfully sent, false indicates failure in sending email.

For example, the function may be used as follows in XSLT. This example constructs a variable to hold the mail-client configuration and constructs the content as html:

<xsl:variable name="mailSetup" select="map{'to':'recipient@example.com', 'from':'sender@example.com', 'smtp-server':'smtp.example.com', 'username':'user@example.com', 'password':'pass'}"/> <xsl:variable name="html"> <html> <body> <h1>Saxonica Email</h1> <p>Test email</p> </body> </html> </xsl:variable> <xsl:value-of select="saxon:send-mail($mailSetup, 'Test email' , $html, ())"/>