Open E-Mail Form – letting the user write a prefilled mail¶

The command "Open E-Mail Form" opens a mail form with prefilled recipients, subject, text and attachments. The user can change the mail and click send; a second action then sends it. This page is for administrators who build "Reply to customer" or "Send offer" buttons.

1. At a glance¶


Purpose	Show a prefilled mail form that the user edits and sends
Typical use	Send an offer with the stored PDF attached; reply to a customer from a ticket
Where in the editor	Toolbar menu "UI" → "Open E-Mail Form"
Needs a user interface	No – without one, the send action runs at once with the prefilled values (section 3)
Related	Send E-Mail, Add File

How it works¶

"Open E-Mail Form" opens the form. The form itself sends nothing.
When the user clicks the send button, nexxcite runs the action selected as "Send Action".
The send action receives the edited mail in the special variables "Send E-Mail Metadata" and "Send E-Mail Attachments" (see Variables) and sends it with a Send E-Mail command.

2. Settings¶

"Display Name", "Description" and "Execution Condition" are on the tab "General" (see Actions). Text settings are expressions.

Tab "General"¶

Setting	Meaning	Default
"Dialog Location"	"Modal" (over the page), "Sidebar" (panel on the right) or "None" (not as a dialog)	"None"
"Format"	"PlainText" or "Html" – how the text is edited	"None" (plain text)
"To", "CC", "BCC"	Prefilled recipients: addresses separated by `;`, or a JSON array; `Name <address>` is allowed	Empty
"Subject", "Body"	Prefilled subject and text	Empty
"Address Suggestions Source"	Where the suggested addresses come from: "Expression" (a fixed list) or "Query" (an address book that is searched while the user types, see below)	"Expression"
"Address Suggestions"	Only with source "Expression": addresses offered while the user types, same format as the recipients. Computed once when the form opens.	Empty
"Address Entity"	Only with source "Query": the entity that holds the addresses, for example "Contact". Only entities with full text search are offered.	Required for "Query"
"Address Field"	Only with source "Query": the text field of the address entity that holds the mail address	Required for "Query"
"Suggestion Preview Form"	Only with source "Query": the form each found record is shown with in the suggestion list – keep it compact, for example name, company and address	Required for "Query"
"Allow suggested addresses only"	The user can only choose suggested addresses	Off
"Don't prompt UI"	Shows no form, also where a user interface is attached: the send action runs at once with the prefilled values (section 3)	Off

Tab "Address Query"¶

Only shown with the source "Query". The conditions narrow which records of the address entity are suggested, for example only active contacts or only the contacts of the current customer. They are edited like a query; the right side of a condition is evaluated for the record the action works on. Without conditions every record of the address entity can be found.

Tab "Advanced"¶

Setting	Meaning	Default
"Hide To", "Hide CC", "Hide BCC", "Hide Subject", "Hide Body"	Hides the field	Off
"To read only", "CC read only", "BCC read only", "Subject read only", "Body read only"	Shows the field but does not let the user change it	Off
"Send Button Text"	Text of the send button	Empty: `Send`
"Cancel Button Text"	Text of the cancel button	Empty: `Cancel`

Tab "Action"¶

Setting	Meaning	Default / Required
"Send Action"	The action that runs when the user clicks send. Without it, the send button does nothing.	Required
"Value Templates"	Values for input variables of the send action: "Argument" (an input variable of the send action) and "Value" (an expression). The values are computed when the form opens, not when send is clicked.	Empty

Tab "Attachments"¶

Setting	Meaning	Default
"Allow upload"	Users can attach files of their own from their device, in addition to the attachment sets	Off
"Max File Size (MB)"	Upper bound for one uploaded file, in megabytes. Only used with "Allow upload".	Empty: 20 MB
"Max Total Size (MB)"	Upper bound for all attachments of the mail together, in megabytes – files of the attachment sets and uploaded files alike	Empty: no limit

The plus button adds an attachment set: stored files that the form offers.

Setting	Meaning
"File Provider"	"Azure Blob Storage" or "S3 Storage"
"Provider Credentials"	Credentials of the storage
"Identifier"	Expression for the identifier the files are stored under – the same as in a files form block or in Add File
"Availability"	"Make available": the files are listed and the user can tick them. "Attach by default": the files are attached from the start; the user can remove them. "None" (default): the set offers nothing.

A set without provider, credentials or identifier is ignored.

In the form, every file is shown as a chip. Offered files that are not attached have a dashed border; a click attaches or detaches them. Files attached by default can be detached and attached again.

3. Behaviour¶

All expressions, attachment sets and value templates are evaluated when the command runs.
With a user interface, the form opens. The command – and with it the action – is done as soon as the form is shown; the rest of the action does not wait for the user.
When the user clicks send, the send action runs on its own, on the same record, with
"Send E-Mail Metadata": JSON with To, Cc, Bcc (each an array of addresses), Subject and Body as the user left them,
"Send E-Mail Attachments": JSON with Count and a Files array (FileName, MimeType, FileSize, Base64Data) of the attached files,
the values of the "Value Templates".
Cancel closes the form; nothing runs.
Uploads: with "Allow upload" on, the form shows an upload area. The user can pick files or drop them there; each one is attached and can be removed again. A file larger than "Max File Size (MB)" is not attached, and the form says so. "Max Total Size (MB)" works the same way for all attachments together: a file that would exceed it – uploaded or ticked – is not attached. If the files attached by default already exceed it, the form says so and the send button stays disabled until the user detaches files. Uploaded files are only passed to the send action in "Send E-Mail Attachments", like all other attachments – they are not stored with the record.
Address suggestions with the source "Query": nothing is loaded when the form opens. As soon as the user types into To, CC or BCC, nexxcite searches the address entity for the typed text (full text search within the "Address Query") and lists up to 20 matching records with the "Suggestion Preview Form". Picking a record adds only its address from "Address Field" to the recipients – the mail shows and sends plain addresses, as with the source "Expression". Records without an address are not listed. A typed text that contains @ can still be added as an address of its own with Enter, a comma or a semicolon, unless "Allow suggested addresses only" is on.
With "Don't prompt UI" on, or without a user interface – for example in a scheduled action, a background rule or a call through the REST API – no form is shown. The send action runs at once with the prefilled values and only the attachments of sets with "Attach by default", as if the user had clicked send without changing anything. Without a send action, the command is skipped.

The send action decides what is actually sent. It can, for example, add a fixed BCC address or refuse to send without a subject.

4. Examples¶

Address book with many contacts. Instead of computing all addresses up front, set "Address Suggestions Source" to Query, "Address Entity" to "Contact", "Address Field" to its mail field and "Suggestion Preview Form" to a small form with name and company. In the tab "Address Query", add the condition "Active" Equals true. The user types "mei" and gets the matching contacts; a click adds the address of the contact.

"Send offer" button on an offer record.

"Open E-Mail Form" with
- "Dialog Location" Modal, "Format" Html
- "To" = the mail field of the contact, "Subject" Our offer followed by the offer number
- "Body" = an HTML text with greeting and signature
- attachment set with the identifier offer- + record ID and "Availability" Attach by default
- "Send Action" Send offer mail
The action "Send offer mail" contains one Send E-Mail command:
- "To", "CC", "BCC", "Subject", "Body" read from "Send E-Mail Metadata" with Modify Value expressions (rule JObjectJsonPathValue, paths To, Cc, Bcc, Subject, Body) – the recipient arrays can be used as they are
- "Attachments" = the special variable "Send E-Mail Attachments"
- "Format" Html

5. Limitations¶

Without "Allow upload", users can only attach the files of the attachment sets.
"Max File Size (MB)" applies to each uploaded file; "Max Total Size (MB)" to all attachments together. With "Don't prompt UI" or without a user interface, "Max Total Size (MB)" is not checked – the files attached by default are sent as they are. Uploaded files are held in memory until the mail is sent; your mail server may still reject a mail that is larger than it accepts.
With the source "Query" the address entity needs full text search. The search finds records by the fields that take part in the full text search of the entity, and lists at most 20 records – typing more narrows the list.
The action that opened the form does not learn whether the user sent the mail.
In a background run the mail is sent without anyone seeing it. If an action must only ever send after a user has checked the mail, do not run it in the background.
Value templates are computed when the form opens. Changes to the record while the form is open do not reach them.