diff --git a/content/en/docs/refguide/modeling/integration/send-email-action.md b/content/en/docs/refguide/modeling/integration/send-email-action.md new file mode 100644 index 00000000000..b54aefda28b --- /dev/null +++ b/content/en/docs/refguide/modeling/integration/send-email-action.md @@ -0,0 +1,216 @@ +--- +title: "Send Email" +url: /refguide/send-email-action/ +weight: 20 +description: "Describes how to use Send Email microflow activity, which sends an email directly from a microflow in Studio Pro." +#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. +--- + +## Introduction + +The **Send Email** activity allows you to send an email directly from a [microflow](/refguide/microflows/). Within a single activity you configure the email server connection, the authentication method, the sender and recipients, the message content, and any attachments. You can also test the connection and send a test email from Studio Pro while your app is running, without having to trigger the microflow. + +{{% alert color="warning" %}} +Before sending email from a production app, review [Before Going to Production](#production) for guidance on authentication, credential storage, and email deliverability (SPF, DKIM, and DMARC). +{{% /alert %}} + +Each **Send Email** activity holds its own connection and message configuration; connection settings are not shared automatically between activities. To reuse the same server settings across multiple activities, store them in [Constants](/refguide/constants/) and reference those constants from each activity — see [Connection](#connection). + +## Properties + +Double-click the **Send Email** activity to open its dialog box. The dialog box is organized into the following tabs: + +- [General](#general) – configure the sender, the security method, and the server connection +- [Message](#message) – configure the recipients, custom headers, message body, and attachment +- [Test Email](#test-email) – send a test email to verify your configuration + +## General Tab {#general} + +The **General** tab configures how Studio Pro connects and authenticates to the email (SMTP) server, and which address the email is sent from. + +### Sender's Details {#senders-details} + +#### Email ID (From) + +The **From** address — the email address that the email is sent from. You can type a value directly, or click **Edit…** to define the value using a [microflow expression](/refguide/expressions/). + +{{% alert color="info" %}} +The **From** address must be an address that the configured email server is allowed to send on behalf of. Many providers reject messages, or mark them as spam, when the **From** address does not match an authenticated, verified sender. This field is labeled **Email ID (From)** in the dialog box; it is the sender ("From") address, not a message identifier. +{{% /alert %}} + +### Security Method {#security-method} + +The **Security method** section determines how the connection authenticates to the email server. The connection uses **basic authentication** — a username and password. Configure the following parameters in the table by selecting a row and clicking **Edit** (or double-clicking the row). Each value is defined using a [microflow expression](/refguide/expressions/). + +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------------ | +| Username | String | The username used to authenticate to the email server. | +| Password | String | The password used to authenticate to the email server. | + +{{% alert color="warning" %}} +Basic authentication (username and password) is deprecated or disabled by default on several major email providers, including **Google Workspace** and **Microsoft 365**, unless the tenant administrator has explicitly re-enabled it. To send email through these providers, either re-enable SMTP basic authentication for the account (where your administrator's policy allows it) or use a provider that supports basic SMTP authentication. +{{% /alert %}} + +{{% alert color="warning" %}} +Avoid hard-coding a **Password** as a literal value in the microflow, as it would then be stored in the app model. Instead, provide the credential through a mechanism that keeps it out of the model — for example a [constant](/refguide/constants/) whose value is set per environment. Never commit real credentials to version control. +{{% /alert %}} + +### Connection {#connection} + +The **Connection** section configures how Studio Pro reaches the email server. + +| Property | Type | Default Value | Description | +| --------------------- | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Email Protocol | String | SMTP | The protocol used to send email. This property is read-only. | +| Security Type | Enumeration | TLS | The transport security used for the connection: **None**, **SSL**, or **TLS**. | +| Check Server Identity | Boolean | No | Whether to verify the server's identity (certificate). This option is only enabled when **Security Type** is set to **SSL**. | +| Timeout (ms) | Integer | 20000 | The connection timeout, in milliseconds. | + +In addition, configure the following parameters in the table by selecting a row and clicking **Edit** (or double-clicking the row). Each value is defined using a [microflow expression](/refguide/expressions/). + +| Parameter | Type | Description | +| ----------- | ------- | --------------------------------------- | +| Server Host | String | The address of the email (SMTP) server. | +| Server Port | Integer | The port of the email (SMTP) server. | + +{{% alert color="info" %}} +Connection details such as the **Server Host**, **Server Port**, and the **Email ID (From)** are commonly stored as [Constants](/refguide/constants/) so that they can differ per environment instead of being hard-coded in the microflow. Referencing the same constants from multiple **Send Email** activities also lets you update the server settings in one place instead of editing each activity individually. +{{% /alert %}} + +### Test Connection {#test-connection} + +Click **Test Connection** to verify that the configured connection and authentication settings are valid. + +{{% alert color="info" %}} +**Test Connection** is only enabled when your app is running and the required connection fields (**Server Host** and **Server Port**) are provided as literal or constant values. A message indicates whether the connection was successful. +{{% /alert %}} + +## Message Tab {#message} + +The **Message** tab configures the recipients, custom headers, message content, and attachment. + +### Receiver's Details {#receivers-details} + +Configure the recipients in the table by selecting a row and clicking **Edit** (or double-clicking the row). Each value is defined using a [microflow expression](/refguide/expressions/). + +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------ | +| To | String | The primary recipient(s) of the email. | +| Cc | String | The carbon-copy recipient(s) of the email. | +| Bcc | String | The blind carbon-copy recipient(s) of the email. | + +### Custom Headers {#custom-headers} + +The **Custom headers** section allows you to add custom email headers. Use the toolbar buttons to manage headers: + +- **Add** – add a new custom header +- **Edit** – edit the selected custom header +- **Delete** – remove the selected custom header + +Each custom header has the following properties: + +| Property | Description | +| -------- | ---------------------------------------------------------------------------------------------- | +| Name | The name of the header. It can only contain letters, digits, and hyphens, and cannot be empty. | +| Value | The value of the header. It cannot be empty and must not contain line breaks. | + +### Message Body {#message-body} + +Configure the subject and body in the table by selecting a row and clicking **Edit** (or double-clicking the row). + +| Parameter | Type | Description | +| ------------------------- | ------ | ----------------------------------------- | +| Subject | String | The subject line of the email. | +| Message body (Plain Text) | String | The plain-text version of the email body. | +| Message body (HTML) | String | The HTML version of the email body. | + +Each of these fields can be defined either as a plain text or as a **string template**. A string template is fixed text with `{1}`, `{2}`, … placeholders whose values are of type [microflow expression](/refguide/expressions/) and come from parameter expressions evaluated against the surrounding microflow. For example: + +```text +Subject: "Order {1} confirmed" + {1} → $Order/OrderNumber + +Body: "Hi {1}, your order ships on {2}." + {1} → $Order/Customer/FirstName + {2} → formatDateTime($Order/ShipDate, 'yyyy-MM-dd') +``` + +Note the following about templates: + +- The subject, the plain-text body, and the HTML body each have their own template. For a given field, use either the plain value or its template consistently. +- Keep placeholder numbering contiguous (`{1}`, `{2}`, …), and make sure every placeholder has a corresponding parameter expression. +- Only reference variables that exist in the microflow's scope at the activity's position. If the data is not yet available, retrieve it earlier in the flow. +- The HTML and plain-text bodies are independent; populate only the one(s) you need. + +### Attachment {#attachment} + +In the **Attachment** section, select a microflow variable to attach to the email. + +Only variables of type _System.FileDocument_, _List of System.FileDocument_, or their specializations can be attached. The variable must exist in the microflow's scope before the **Send Email** activity — the file must already have been retrieved or created earlier in the flow. + +{{% alert color="info" %}} +The **Send Email** activity does not impose its own attachment size limit. The maximum message and attachment size is determined by the receiving email server or provider, which rejects messages that exceed its limit. Check your provider's documentation for the applicable maximum. +{{% /alert %}} + +## Test Email Tab {#test-email} + +The **Test Email** tab lets you send a test email to verify your configuration from Studio Pro, without triggering the microflow. + +### Test Email Details {#test-email-details} + +#### Use Template for Test Email + +When selected, the subject and body fields use the string templates configured on the [Message](#message) tab. Because template placeholders reference microflow variables that are not available while testing, click the edit icon next to each field to provide test values for the template parameters. + +When not selected, you can enter the subject and body directly: + +| Property | Description | +| ------------------------- | ---------------------------------------------- | +| To | The recipient of the test email. | +| Subject | The subject line of the test email. | +| Message body (Plain Text) | The plain-text version of the test email body. | +| Message body (HTML) | The HTML version of the test email body. | + +### Send Test Email {#send-test-email} + +Click **Send Test Email** to send the test email using the current configuration. A message indicates whether the test email was sent successfully. + +{{% alert color="info" %}} +**Send Test Email** is only enabled when your app is running and the **To** field is provided. +{{% /alert %}} + +## Error Handling {#error-handling} + +Sending email can fail at runtime for reasons outside your app's control — for example, the email server is unreachable, the connection times out, authentication is rejected, or a recipient address is invalid. When this happens, the **Send Email** activity raises and logs an error. + +Handle these failures the same way as for any other microflow activity, by configuring an [error handler](/refguide/error-handling-in-microflows/) on the activity. This lets you, for example, log the failure, notify the user, or retry through an alternative path instead of letting the whole microflow fail. Because email delivery depends on external systems, wrapping the **Send Email** activity in error handling is strongly recommended for production apps. + +## Before Going to Production {#production} + +Sending email reliably from a production app depends on more than the activity configuration. Review the following before you deploy. + +### Authentication and Credentials + +- This version of the activity supports [basic authentication](#security-method) (username and password) only. Confirm your email provider permits SMTP basic authentication — **Google Workspace** and **Microsoft 365** disable it by default — or use a provider that does. +- Do not hard-code credentials in the microflow model. Supply them through per-environment [constants](/refguide/constants/) so that secrets — the password in particular — are not stored in the app model or version control. + +### Email Deliverability (SPF, DKIM, and DMARC) + +For your emails to be accepted and not marked as spam, the sending domain must be configured correctly at the DNS level: + +- **SPF** – authorizes which servers may send email for your domain. +- **DKIM** – cryptographically signs your messages so recipients can verify they were not altered. +- **DMARC** – tells receiving servers how to handle messages that fail SPF or DKIM checks. + +If these records are missing or misconfigured, receiving servers may reject your messages or route them to spam, even when the activity reports that the email was sent successfully. Set these up with your email provider and domain administrator before going live. + +{{% alert color="info" %}} +When deploying to Mendix Cloud, also see [Sending Email](/developerportal/deploy/sending-email/) for supported providers and SMTP configuration guidance. +{{% /alert %}} + +## Read More + +- [Sending Email](/developerportal/deploy/sending-email/) – external email providers and SMTP configuration for Mendix Cloud +- [Error Handling in Microflows](/refguide/error-handling-in-microflows/) +- [Constants](/refguide/constants/) +- [Microflow Expressions](/refguide/expressions/)