Name

p:send-mail — The standard p:send-mail step.

Synopsis

The p:send-mail step sends an email message.

Input portPrimarySequenceContent types
source✔ ✔ any 
Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault value
authmap(xs:string, item()+)?()
parametersmap(xs:QName, item()*)?()
serializationmap(xs:QName,item()*)?()
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
  |   <p:input port="source" sequence="true" content-types="any"/>
  |   <p:output port="result" content-types="application/xml"/>
  |   <p:option name="serialization" as="map(xs:QName,item()*)?"/>
5 |   <p:option name="auth" as="map(xs:string, item()+)?"/>
  |   <p:option name="parameters" as="map(xs:QName, item()*)?"/>
  |</p:declare-step>
Errors
CodeDescription
err:XC0159It is a dynamic error (err:XC0159) if any key in the “auth” map is associated with a value that is not an instance of the required type.
err:XC0160It is a dynamic error (err:XC0160) if any key in the “parameters” map is associated with a value that is not an instance of the required type.
err:XC0161It is a dynamic error (err:XC0161) if the first document on the source port does not conform to the required format.
err:XC0162It is a dynamic error (err:XC0162) if the email cannot be send.
Implementation defined features

Description

The p:send-mail step is a standard XProc 3.1 step. It is also described on XProcRef.org.

The XML Calabash implementation of p:send-mail relies on the javax.mail package to send mail. The javax.mail package is configured with a set of properties. There are two ways to configure the properties: with cc:send-mail in a configuration file and with the parameters option. If an option is specified in both places, the value from the parameters option is used. (The send-authentication property is true by default if a username or password is provided in the auth parameter and false otherwise).

The following mappings apply:

p:send-mail configurationjavax.mail configuration
hostmail.smtp.host
portmail.smtp.port
send-authenticationmail.smtp.auth

In addition, if the debug property is true, javax.mail session debugging is enabled.

Any other configuration name/value pairs are passed through unchanged.

The following configuration, for example, will send mail using GMail’s SMTP server (in September, 2025; GMail authentication may change over time):

p:send-mail configurationValue
hostsmtp.gmail.com
port465
send-authenticationtrue
mail.smtp.socketFactory.port465
mail.smtp.socketFactory.classjavax.net.ssl.SSLSocketFactory
mail.smtp.fallbackfalse
mail.smtp.starttls.enabletrue

You must use your full GMail address as the username and an application-specific password as the password.

You might arrange for this configuration by specifying a cc:send-mail element in your configuration:

1 |<cc:send-mail host='smtp.gmail.com' port='465'
  |              mail.smtp.socketFactory.port='465'
  |              mail.smtp.socketFactory.class='javax.net.ssl.SSLSocketFactory'
  |              mail.smtp.socketFactory.fallback='false'
5 |              mail.smtp.starttls.enable='true'/>

And then calling p:send-mail with only the auth option specifying the username and password. Or, conversely, by passing all the values in the parameters option:

 1 |<p:send-mail
   |    parameters="map{'host': 'smtp.gmail.com', 'port': '465',
   |                    'mail.smtp.socketFactory.port': '465',
   |                    'mail.smtp.socketFactory.class': 'javax.net.ssl.SSLSocketFactory',
 5 |                    'mail.smtp.socketFactory.fallback': 'false',
   |                    'mail.smtp.starttls.enable': 'true'}"
   |             auth="map{'username':'myusername@gmail.com',
   |                       'password':'my-secret-app-password'}">
   |  <p:with-input>
10 |    …
   |  </p:with-input>
   |</p:send-mail>

Or any combination of the two that suits you.