# email action

\[Orbeon Forms PE only]

## Introduction

The `email` action sends an email with optionally XML form data, attachments, and PDF. It is automatically associated with the "Email" button, but can be called by a process.

## Parameters

* \[SINCE Orbeon Forms 2022.1] `template`: Optional name of the email template to use.
* PDF parameters (when a rendered PDF version of the form is attached to the email):
  * `use-pdf-template`
  * `pdf-template-name`
  * `pdf-template-lang`
* [\[SINCE Orbeon Forms 2023.1\]](/release-notes/orbeon-forms-2023.1.md) `data-format-version`: The data format version for the XML data, if included as email attachment.
  * `4.0.0`: the default (which matches the backward compatibility format of the data, as stored in the database)
  * `4.8.0`
  * `2019.1.0`
* [\[SINCE Orbeon Forms 2023.1\]](/release-notes/orbeon-forms-2023.1.md) `match`: The behaviour to use when multiple templates are found. Can be `first` (default) or `all`. If `all`, then all matching templates are used (i.e. one email per template is sent). If `first`, then only the first matching template is used.
* \[SINCE Orbeon Forms 2024.1.1] `s3-store`: If `true`, email attachments are stored in an S3 bucket in addition to being sent via email. If `false` or absent, attachments are only sent via email. See [S3 storage](/form-runner/features/s3.md) for more information about how to use this feature.
* `lang`: Optional language override for email template selection. If not provided, the current form language is used.

## Configuration properties

See [Email configuration properties](/configuration/properties/form-runner/form-runner-detail-page/form-runner-email.md).

## Email template selection

When an email is sent, the following algorithm is used to determine what template is used:

* If no email template is defined, then a default title and body defined in the Form Runner resources is used.
* If at least one email template is defined:
  * All the templates that are for a specific language which doesn't correspond to the current language are filtered out.
  * If the `template` parameter is present, all the templates whose name doesn't match the value of the `template` parameter are filtered out.
  * [\[SINCE Orbeon Forms 2023.1\]](/release-notes/orbeon-forms-2023.1.md) If the "Enable this template only if the following formula evaluates to true" XPath expression is present and evaluates to `false`, the template is filtered out.
  * [\[SINCE Orbeon Forms 2023.1\]](/release-notes/orbeon-forms-2023.1.md) If more than one template is left and the `match` parameter is set to `first` or absent (the default), then the first template is used, following the order in which they are defined in the form. If the `match` parameter is set to `all`, then all remaining templates are used.
  * If no template is left, then no email is sent.

## Example

Here is an example of a `submit` process for the `acme`/`order` form, which saves data and then sends an email while specifying the email template to use as well as the XML data format version to use for the attachment:

```xml
<property as="xs:string"  name="oxf.fr.detail.process.submit.acme.order">
    require-uploads
    then validate-all
    then save
    then email(
        data-format-version = "4.0.0",
        template = "acme-order"
    )
    then success-message("email-success")
</property>
```

## See also

* [Form Runner email properties](/configuration/properties/form-runner/form-runner-detail-page/form-runner-email.md)
* [Form Builder email settings](/form-builder/advanced/email-settings.md)
* [PDF templates](/form-runner/features/pdf-templates.md)
* [S3 storage](/form-runner/features/s3.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/form-runner/advanced/buttons-and-processes/actions-form-runner/actions-form-runner-email.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.