XProc 3.1: mail steps

Community Group Report

Latest editor’s draft:
https://spec.xproc.org/master/head/mail/
Editors:
Norman Walsh
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Participate:
GitHub xproc/3.0-steps
Report an issue
Changes:
Diff against current “status quo” draft
Commits for this specification

This document is also available in these non-normative formats: XML and HTML with automatic change markup courtesy of DeltaXML.

Copyright © 2018, 2019, 2020 the Contributors to the XProc 3.1: mail steps specification, published by the XProc Next Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

This specification describes optional mail related steps for XProc 3.1: An XML Pipeline Language.

Status of this Document

This specification was published by the XProc Next Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

If you wish to make comments regarding this document, please send them to xproc-dev@w3.org. (subscribe, archives).

Note

This draft is a “last call” draft. This version is stable and will not be updated.

1. Introduction

This specification describes optional mail related XProc steps. A machine-readable description of these steps may be found in steps.xpl.

Familarity with the general nature of [XProc 3.1] steps is assumed.

2. Step library

2.1. p:send-mail

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

Summary

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()*)?()
Errors
Error codeDescription
err:XC0159It 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.
err:XC0160It 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.
err:XC0161It is a dynamic error if the first document on the source port does not conform to the required format.
err:XC0162It is a dynamic error if the email cannot be send.
Implementation details
ImplementationDescription
DefinedOther key value pairs in “auth” are implementation-defined
DefinedIt is implementation-defined which other key/value pairs in the parameters option are supported.
DefinedOther key value pairs in “auth” are implementation-defined
DefinedIf no values for “host” or “port” is specified, it it implementation-defined which server and port is used.
Declaration

<p:declare-step type="p:send-mail">
     <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()*)?"/>  
     <p:option name="auth" as="map(xs:string, item()+)?"/>         
     <p:option name="parameters" as="map(xs:QName, item()*)?"/>    
</p:declare-step>

The first document on the source port is expected to conform to [XML format for mail]. It is a dynamic error (err:XC0161) if the first document on the source port does not conform to the required format. Any additional documents are treated as attachments.

If the mail was send successfully a single c:result document whose content is “true” appears on the result port. It is a dynamic error (err:XC0162) if the email cannot be send.

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

The p:send-mail step has the following options:

serialization

The serialization option is used to control the serialization of documents for constructing the mail. If a document has a “serialization” document property, the effective value of the serialization options is the union of the two maps, where the entries in the “serialization” document property take precedence.

auth

If the mail service requires an authentication to send mails, these can be supplied using the auth option.

The following standard keys are defined:

username (xs:string)

The username.

password (xs:string)

The password.

Other key value pairs in “auth” are implementation-defined.It 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.

parameters

The parameters option can be used to supply additional information for constructing and sending mails. A number of parameters are defined in this specification. It is implementation-defined which other key/value pairs in the parameters option are supported.

send-authorization (xs:boolean)

If the key is associated with false no authentication will be used when sending a mail.

host (xs:string)

The SMTP server.

port (xs:unsignedShort)

The port.

Other key value pairs in “auth” are implementation-defined.It 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.

If no values for “host” or “port” is specified, it it implementation-defined which server and port is used.

Document properties

No document properties are preserved.

3. Step Errors

These steps can raise dynamic errors.

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see Dynamic Errors in XProc 3.0: An XML Pipeline Language.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

The following errors can be raised by this step:

err: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.

See: p:send-mail

err: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.

See: p:send-mail

err:XC0161

It is a dynamic error if the first document on the source port does not conform to the required format.

See: p:send-mail

err:XC0162

It is a dynamic error if the email cannot be send.

See: p:send-mail

A. Conformance

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.

Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.

[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]

[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]

A.1. Implementation-defined features

The following features are implementation-defined:

  1. Other key value pairs in “auth” are implementation-defined See Section 2.1, “p:send-mail”.
  2. It is implementation-defined which other key/value pairs in the parameters option are supported. See Section 2.1, “p:send-mail”.
  3. Other key value pairs in “auth” are implementation-defined See Section 2.1, “p:send-mail”.
  4. If no values for “host” or “port” is specified, it it implementation-defined which server and port is used. See Section 2.1, “p:send-mail”.

B. References

[XML format for mail] Internet Draft: An XML Format for mail and other messages. G. Klyne. Network Working Group, IETF, April 2002.

[XProc 3.1] XProc 3.1: An XML Pipeline Language. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.

C. Glossary

dynamic error

A dynamic error is one which occurs while a pipeline is being evaluated.

implementation-defined

An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

implementation-dependent

An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.

D. Ancillary files

This specification includes by reference a number of ancillary files.

steps.xpl

An XProc step library for the declared steps.