p:send-mail (3.1)

Sends an email message.

Summary
Description
- Step parameters
- Authentication parameters
Examples
- Basic usage
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:send-mail">
  <input port="source" primary="true" content-types="any" sequence="true"/>
  <output port="result" primary="true" content-types="application/xml" sequence="false"/>
  <option name="auth" as="map(xs:string, item()+)?" required="false" select="()"/>
  <option name="parameters" as="map(xs:QName, item()*)?" required="false" select="()"/>
  <option name="serialization" as="map(xs:QName,item()*)?" required="false" select="()"/>
</p:declare-step>

The p:send-mail step sends an email message. This message, described in the XML format for mail, must appear on the source port.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`source`	`input`	`true`	`any`	`true`	The email message to send. The first document on this port must be an XML document describing the email message. It must conform to the XML format for mail. The `<content>` element of this email message specification may contain either text or HTML. To send some other type as message body, you must leave the `<content>` element out of the first document and supply the body as a second document. Any additional documents are treated as email attachments.
`result`	`output`	`true`	`application/xml`	`false`	If the email was sent successfully, this port will emit a short XML document containing just `<c:data>true</c:data>` (the `c` prefix here is bound to the `http://www.w3.org/ns/xproc-step` namespace). If something went wrong during the sending operation, error `XC0162` is raised.

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

any

true

The email message to send. The first document on this port must be an XML document describing the email message. It must conform to the XML format for mail.

The <content> element of this email message specification may contain either text or HTML. To send some other type as message body, you must leave the <content> element out of the first document and supply the body as a second document.

Any additional documents are treated as email attachments.

result

output

true

application/xml

false

If the email was sent successfully, this port will emit a short XML document containing just <c:data>true</c:data> (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

If something went wrong during the sending operation, error XC0162 is raised.

Options:

Name	Type	Req?	Default	Description
`auth`	`map(xs:string, item()+)?`	`false`	`()`	A map containing authentication parameters. See Authentication parameters for more information.
`parameters`	`map(xs:QName, item()*)?`	`false`	`()`	a map containing additional information for constructing and sending the email. See Step parameters for more information.
`serialization`	`map(xs:QName,item()*)?`	`false`	`()`	This option controls the serialization of any documents involved in constructing the mail. If the source document has a `serialization` document-property, the two sets of serialization properties are merged (properties in the document-property have precedence).

Name

Type

Req?

Default

Description

auth

map(xs:string, item()+)?

false

()

A map containing authentication parameters. See Authentication parameters for more information.

parameters

map(xs:QName, item()*)?

false

()

a map containing additional information for constructing and sending the email. See Step parameters for more information.

serialization

map(xs:QName,item()*)?

false

()

This option controls the serialization of any documents involved in constructing the mail.

If the source document has a serialization document-property, the two sets of serialization properties are merged (properties in the document-property have precedence).

Description

The p:send-mail step attempts to send an email message using SMTP. The address of the SMTP server and other details can be supplied using the Step parameters and Authentication parameters.

The email message itself must be described using the XML format for mail. Examples can be found in the specification or in the Basic usage example below.

Step parameters

The parameters option contains additional information used for constructing and sending the email message. It is a map that associates parameters (the keys in the map) with values. The following parameters are defined:

Parameter	Datatype	Description
`send-authorization`	`xs:boolean`	If `true` (default), the authentication information provided in the Authentication parameters will be used. If `false`, no authentication will be used when sending the mail.
`host`	`xs:string`	The URL of the SMTP server to use. If no value for `host` is specified, it is implementation-defined which server is used.
`port`	`xs:unsignedShort`	The IP port to use when sending the mail to the SMTP server. If no value for `port` is specified, it is implementation-defined which port is used.

Parameter

Datatype

Description

send-authorization

xs:boolean

If true (default), the authentication information provided in the Authentication parameters will be used. If false, no authentication will be used when sending the mail.

host

xs:string

The URL of the SMTP server to use.

If no value for host is specified, it is implementation-defined which server is used.

port

xs:unsignedShort

The IP port to use when sending the mail to the SMTP server.

If no value for port is specified, it is implementation-defined which port is used.

Depending on the XProc processor used, the parameters map may contain other, implementation-defined, keys.

Authentication parameters

The auth option contains additional information used for the authentication with the SMTP server. It is a map that associates parameters (the keys in the map) with values. The following authentication parameters are defined:

Parameter	Datatype	Description
`username`	`xs:string`	The username used for authentication.
`password`	`xs:string`	The password used for authentication.

Depending on the XProc processor used, the auth map may contain other, implementation-defined, keys.

Examples

Basic usage

Below a very basic example of how to construct an email message and use p:send-mail to send it. I hope I get a lot of messages like this ;).

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source">
    <p:inline>
      <emx:Message xmlns:emx="URN:ietf:params:email-xml:" xmlns:rfc822="URN:ietf:params:rfc822:">
        <rfc822:from>
          <emx:Address>
            <emx:adrs>mailto:someone@…</emx:adrs>
            <emx:name>John Doe</emx:name>
          </emx:Address>
        </rfc822:from>
        <rfc822:to>
          <emx:Address>
            <emx:adrs>mailto:erik@xatapult.nl</emx:adrs>
            <emx:name>Erik Siegel</emx:name>
          </emx:Address>
        </rfc822:to>
        <rfc822:subject>XProcRef is awesome</rfc822:subject>
        <emx:content type="text/plain" xml:space="preserve">
          Hi Erik,
          
          XProcRef is awesome! Congrats and kudos!
          
          Regards,
          John Doe
        </emx:content>
      </emx:Message>
    </p:inline>
  </p:input>

  <p:output port="result"/>

  <p:send-mail>
    <p:with-option name="auth" select="map{
      'username': '…', 
      'password': '…'
    }"/>
    <p:with-option name="parameters" select="map{
      'send-authorization': true(),
      'host': '…',
      'port': …   
    }"/>
  </p:send-mail>

</p:declare-step>

Additional details

The document appearing on the result port only has a content-type property. It has no other document-properties (also no base-uri).

Errors raised

Error code	Description
`XC0159`	It is a dynamic error if any key in the “`auth`” map is associated with a value that is not an instance of the required type.
`XC0160`	It is a dynamic error if any key in the “`parameters`” map is associated with a value that is not an instance of the required type.
`XC0161`	It is a dynamic error if the first document on the `source` port does not conform to the required format.
`XC0162`	It is a dynamic error if the email cannot be send.

Reference information

This description of the p:send-mail step is for XProc version: 3.1. This is a non-required step (an XProc 3.1 processor does not have to support this).

The formal specification for the p:send-mail step can be found here.

The p:send-mail step is part of categories:

The p:send-mail step is also present in version: 3.0.