From ccfc4e4784b5a89a6324c2f45b2bc96c0fb78189 Mon Sep 17 00:00:00 2001 From: Atul Lahade Date: Wed, 15 Jul 2026 18:21:17 +0530 Subject: [PATCH 1/5] ADCP-25 Send Email Action (Beta) --- .../modeling/integration/send-email-action.md | 216 ++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 content/en/docs/refguide/modeling/integration/send-email-action.md 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/) From 4a6a7b0c623e87e45e9716f5000b8a22ab6588da Mon Sep 17 00:00:00 2001 From: Atul Lahade Date: Thu, 16 Jul 2026 13:03:05 +0530 Subject: [PATCH 2/5] ADCP-25 Send Email Action (Beta) --- .../activities/_index.md | 10 + .../activities/email-activities/_index.md | 17 ++ .../email-activities/send-email-action.md | 216 ++++++++++++++++++ .../activities/send-email.png | Bin 0 -> 1892 bytes 4 files changed, 243 insertions(+) create mode 100644 content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md create mode 100644 content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md create mode 100644 static/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/send-email.png diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/_index.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/_index.md index 365c286b651..d159786e215 100644 --- a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/_index.md +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/_index.md @@ -122,6 +122,16 @@ These activities can only be used in microflows. | {{< figure src="/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/increment-counter.png" alt="increment-counter" link="/refguide/metrics-increment-counter/" max-width=55% class="no-border" >}} | [Increment counter](/refguide/metrics-increment-counter/) | Allows you to increment a counter by 1. | | {{< figure src="/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/gauge.png" alt="gauge" link="/refguide/metrics-gauge/" max-width=55% class="no-border" >}} | [Gauge](/refguide/metrics-gauge/) | Allows you to specify the value of a gauge. | +## Email Activities + +{{% alert color="info" %}} +These activities can only be used in microflows. +{{% /alert %}} + +| Graphic | Name | Description | +| --- | --- | --- | +| {{< figure src="/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/send-email.png" alt="send email" link="/refguide/send-email-action/" max-width=60% class="no-border" >}} | [Send Email](/refguide/send-email-action/) (microflows only) | Allows you to send an email directly from a microflow. | + ## ML Kit Activities [ML Kit activities](/refguide/ml-kit-activities/) are used with a machine learning model. diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md new file mode 100644 index 00000000000..c0b91046e03 --- /dev/null +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md @@ -0,0 +1,17 @@ +--- +title: "Email Activities" +url: /refguide/email-activities/ +weight: 82 +--- + +{{% alert color="info" %}} +These activities can only be used in microflows. +{{% /alert %}} + +## Introduction + +The **Email Activities** section of the [Toolbox](/refguide/view-menu/#toolbox) contains activities you can use for performing email operations directly from a microflow. + +The following are the Email activities you can use in your microflow: + +- [Send Email](/refguide/send-email-action/) diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md new file mode 100644 index 00000000000..b54aefda28b --- /dev/null +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/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/) diff --git a/static/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/send-email.png b/static/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/send-email.png new file mode 100644 index 0000000000000000000000000000000000000000..f712ef224dc9b3ebb73a40678847994daec600fd GIT binary patch literal 1892 zcmV-q2b=hbP)F7{~v&SfD_VVJJ()SrlCy4wo&1NS3Ya zgF5AdXv8eTmt}4-j?E>$WXTc%lO=P`L^s_?Tryu+7Bo|r>2!XWm`%-GVjLUGRFpa) z5f}(&11-gC}vpZ|HD=iJ-dqhJ)49#_+PU04eRFVW^R z^s+$`4GyxULjewA5Orr>RUCmTDZ_WL5IqCfsHk`kD$*bs7gQ4}&#q9ahVLID$f9pl z8&y09%^Rkt0(n;833^XUfFuf9d+6l^u5|*}JAJzyiW^1#-r^I)Uko;WagIk2iT-rE zfSLxN%Oy64h+^_q@`{m}1gy)GVvHw~X~4fhHfCEB!Vx%C@P-g%!BMpWnrE!a1rjDf zGR`EDjmvU)RRmcx9@wx7tv*jN45!Zu=CcF=~9eXz^Oq? z58^VzqylSrYxZN1#0Z|rYS>M5tzqL*W-=r(!Z(3ZFprbEjmuJy*x{EdY$iwyg%reK zNI?vS6vSXiK@5fz#9&B442BfMV1&G{>vXAbw7H=N8L0}aljRr)Mo>Z8x>cW&O&@_DMM7G5E*UR3 z%YMZ?zg@(QhI;5h{bl|73dQLohsAqy(@p$(?ku8V%rVGH3AuV* zl1R*LuX2Q7}9=xn=-iJ-^n6z{z~ z&Zq}L*uS2$w{Q;NoWS{@w9xEJ((Dzrm;T4)#sQQsN)X{L6g-lrWMpFb>+1s^?`Ug< zB{>C2$wPl1@ET$GesBF?aNAzzf0$y;40t~8{y^sl)ONJb9tjaW&cKG=UP>YCV!!Z& z?WKt{0Z>IaE69lxUNP306dSLZMsr7ds}RPYulIc-4A4nN%FCaRS4vlj@WA2CLPlz7 zy5-x?d|I(Z>oXah?QO6xUOM7@Jc5rMs788*mCo6Qjg>n^{fZ5%k@tKdwYw|&pGV~$ zGJNA-^{_7~5w9B!zmo?a7yS%xTlM)N=t0EKmv9JshrHk?3SHZd_K|mZW?}_7;dMDH zHxJ9#uE%F&%p5ASaakA+VTtr*UweDAsJDZ{ntjPKQD!5QY5TXXSti@5Kv6Al}D@lv$hZWN)xl9Ym?#U){lK(FC~F~w@dyHz_83G6u= zsV$4;omuHk%?3s9)Jm!a^H6osKqUB@3$S3bOt<@KOUA{D; z4jYn%<`Bevay=gDV}*wt=d{uK*Mqp66_u4-cyZdugPf=vn%yYM)#p)0o+@*A^S|O( z6a|g+1^G+f@4AP@E6b2Mb(#nj9CmmX=D6`Ug^`)s%toQ`@;Fk{9zM5Zn>|MyGn?aa zd`n2AFET4XS! zAO=GUVlbp2215#BFr**`LkeOrq#y=^1#xge`xCn)2DCbTMTd#*P+sNI?QTe71TVY6 z(A{Se#EtX3@kcu(G2&W>Rv5%VlPduS$VWjy2dULQ^TtSL5{&>ac)>Z@}F)Fzr1QA|B zztr*pPB8oHeHA6+08gOU##%CWXtoywUBHajKj9@ecu@hlut0S1WyL=vM1A{^Ts`^% zX8w>cl_X3BB;x~3qLe}GNle7<6BM0>9vTJq7J9QI4r_Ql6jd&Q85Lw`2ifo{+48)F eX12qH@bUm%8Ldp3%{3eV0000 Date: Thu, 16 Jul 2026 13:12:17 +0530 Subject: [PATCH 3/5] Deleted send email file from integration folder --- .../modeling/integration/send-email-action.md | 216 ------------------ 1 file changed, 216 deletions(-) delete mode 100644 content/en/docs/refguide/modeling/integration/send-email-action.md diff --git a/content/en/docs/refguide/modeling/integration/send-email-action.md b/content/en/docs/refguide/modeling/integration/send-email-action.md deleted file mode 100644 index b54aefda28b..00000000000 --- a/content/en/docs/refguide/modeling/integration/send-email-action.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -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/) From b6fd4fe090ac3ce83c68491fe331bb9d2cb542b9 Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Thu, 16 Jul 2026 15:01:26 +0200 Subject: [PATCH 4/5] Review --- .../activities/email-activities/_index.md | 2 +- .../email-activities/send-email-action.md | 101 ++++++++++-------- 2 files changed, 60 insertions(+), 43 deletions(-) diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md index c0b91046e03..78edc0c5e6e 100644 --- a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md @@ -10,7 +10,7 @@ These activities can only be used in microflows. ## Introduction -The **Email Activities** section of the [Toolbox](/refguide/view-menu/#toolbox) contains activities you can use for performing email operations directly from a microflow. +The activities described in this section are the **Email Activities** section of the **Toolbox**. They contain activities you can use for performing email operations directly from a microflow. The following are the Email activities you can use in your microflow: diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md index b54aefda28b..ec289f0273c 100644 --- a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md @@ -2,27 +2,35 @@ 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." +description: "Describes how to use the Send Email microflow activity to send emails 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. +The **Send Email** activity allows you to send an email directly from a microflow. Within a single activity, you configure the following: + +* Email server connection +* Authentication method +* Sender and recipients +* Message content +* 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. + +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 the [Connection](#connection) section below for more information. {{% 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). +Before sending emails from a production app, review the [Before Going to Production](#production) section below 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](#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} @@ -32,15 +40,15 @@ The **General** tab configures how Studio Pro connects and authenticates to the #### 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/). +The **From** address is the email address 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. +The **From** address must be an address 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/). +The **Security method** section determines how the connection authenticates to the email server. The connection uses basic authentication. 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. | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------ | @@ -48,11 +56,13 @@ The **Security method** section determines how the connection authenticates to t | 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. +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 emails through these providers, you can: +* 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. +Avoid hard-coding a password as a literal value in the microflow because 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 whose value is set per environment). Never commit real credentials to version control. {{% /alert %}} ### Connection {#connection} @@ -64,9 +74,9 @@ The **Connection** section configures how Studio Pro reaches the email server. | 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. | +| 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/). +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. | Parameter | Type | Description | | ----------- | ------- | --------------------------------------- | @@ -74,12 +84,12 @@ In addition, configure the following parameters in the table by selecting a row | 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. +Connection details such as the **Server Host**, **Server Port**, and the **Email ID (From)** are commonly stored as [Constants](/refguide/constants/) so 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. +Click **Test Connection** to verify 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. @@ -91,28 +101,28 @@ The **Message** tab configures the recipients, custom headers, message content, ### 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/). +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. | 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. | +| To | String | The primary recipient (or recipients) of the email. | +| Cc | String | The carbon-copy recipient (or recipients) of the email. | +| Bcc | String | The blind carbon-copy recipient (or recipients) 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: +The **Custom headers** section allows you to add custom email headers. Use the toolbar to manage headers: -- **Add** – add a new custom header -- **Edit** – edit the selected custom header -- **Delete** – remove the selected custom header +* **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. | +| Name | The name of the header. This can only contain letters, digits, and hyphens, and cannot be empty. | +| Value | The value of the header. It cannot be empty and cannot contain line breaks. | ### Message Body {#message-body} @@ -124,7 +134,7 @@ Configure the subject and body in the table by selecting a row and clicking **Ed | 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: +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 and come from parameter expressions evaluated against the surrounding microflow. For example: ```text Subject: "Order {1} confirmed" @@ -140,13 +150,13 @@ 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. +- The HTML and plain-text bodies are independent. Populate only the one (or ones) 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. +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. @@ -154,13 +164,13 @@ The **Send Email** activity does not impose its own attachment size limit. The m ## 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. +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 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: @@ -181,31 +191,38 @@ Click **Send Test Email** to send the test email using the current configuration ## 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. +Sending emails can fail at runtime for reasons outside your app's control, such as: + +* The email server is unreachable +* The connection times out +* Authentication is rejected +* 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. +Handle these failures 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. +Review the following before you deploy to a production app. ### 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. +- 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 so 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: +The sending domain must be configured correctly at the DNS level for your emails to be accepted and not marked as spam. -- **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. +- **SPF** – authorizes which servers may send emails 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. +When deploying to Mendix Cloud, refer to [Sending Email](/developerportal/deploy/sending-email/) for supported providers and SMTP configuration guidance. {{% /alert %}} ## Read More From 2cd0e1721aaa5d0dc699fb8fb189d6a26405ee1c Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Thu, 16 Jul 2026 16:16:33 +0200 Subject: [PATCH 5/5] Reformat to match existing docs --- .../email-activities/send-email-action.md | 150 +++++++++++------- 1 file changed, 97 insertions(+), 53 deletions(-) diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md index ec289f0273c..058411f5890 100644 --- a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md @@ -48,12 +48,7 @@ The **From** address must be an address the configured email server is allowed t ### Security Method {#security-method} -The **Security method** section determines how the connection authenticates to the email server. The connection uses basic authentication. 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. - -| 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. | +The **Security method** section determines how the connection authenticates to the email server. The connection uses basic authentication. {{% 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 emails through these providers, you can: @@ -61,32 +56,58 @@ Basic authentication (username and password) is deprecated or disabled by defaul * Use a provider that supports basic SMTP authentication. {{% /alert %}} +#### Username + +The **Username** property is the username used to authenticate to the email server. + +#### Password + +The **Password** property is the password used to authenticate to the email server. + {{% alert color="warning" %}} Avoid hard-coding a password as a literal value in the microflow because 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 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). | - -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. - -| Parameter | Type | Description | -| ----------- | ------- | --------------------------------------- | -| Server Host | String | The address of the email (SMTP) server. | -| Server Port | Integer | The port of the email (SMTP) server. | +The **Connection** field configures how Studio Pro reaches the email 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 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 %}} +#### Email Protocol + +The **Email Protocol** property is the protocol used to send email. This property is read-only. + +Default value: *SMTP* + +#### Security Type + +The **Security Type** property is the transport security used for the connection: **None**, **SSL**, or **TLS**. + +Default value: *TLS* + +#### Check Server Identity + +The **Check Server Identity** option defines whether to verify the server's identity (certificate). This option is only enabled when **Security Type** is set to **SSL**. + +Default value: *No* + +#### Timeout (ms) + +The connection timeout (in milliseconds). + +Default value: *20000* + +#### Server Host + +The **Server Host** property is the address of the email (SMTP) server. + +#### Server Port + +The **Server Port** property is the port of the email (SMTP) server. + ### Test Connection {#test-connection} Click **Test Connection** to verify the configured connection and authentication settings are valid. @@ -103,11 +124,17 @@ The **Message** tab configures the recipients, custom headers, message content, 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. -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------ | -| To | String | The primary recipient (or recipients) of the email. | -| Cc | String | The carbon-copy recipient (or recipients) of the email. | -| Bcc | String | The blind carbon-copy recipient (or recipients) of the email. | +#### To + +The **To** field is the primary recipient (or recipients) of the email. + +#### Cc + +The **Cc** field is the carbon-copy recipient (or recipients) of the email. + +#### Bcc + +The **Bcc** field is the blind carbon-copy recipient (or recipients) of the email. ### Custom Headers {#custom-headers} @@ -117,24 +144,17 @@ The **Custom headers** section allows you to add custom email headers. Use the t * **Edit** – edit the selected custom header * **Delete** – remove the selected custom header -Each custom header has the following properties: +#### Name -| Property | Description | -| -------- | ---------------------------------------------------------------------------------------------- | -| Name | The name of the header. This can only contain letters, digits, and hyphens, and cannot be empty. | -| Value | The value of the header. It cannot be empty and cannot contain line breaks. | +The **Name** property is the name of the header. This can only contain letters, digits, and hyphens, and cannot be empty. -### Message Body {#message-body} +#### Value -Configure the subject and body in the table by selecting a row and clicking **Edit** (or double-clicking the row). +The **Value** property is the value of the header. It cannot be empty or contain line breaks. -| 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. | +### Message Body {#message-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 and come from parameter expressions evaluated against the surrounding microflow. For example: +The following fields can be defined either as plain text or as a string template. A string template is fixed text with `{1}`, `{2}`, … placeholders whose values are of type microflow expression and come from parameter expressions evaluated against the surrounding microflow. For example: ```text Subject: "Order {1} confirmed" @@ -145,17 +165,32 @@ Body: "Hi {1}, your order ships on {2}." {2} → formatDateTime($Order/ShipDate, 'yyyy-MM-dd') ``` -Note the following about templates: +{{% alert color="info" %}} +Consider 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 (or ones) you need. +{{% /alert %}} + +#### Subject + +The **Subject** property is the subject line of the email. -- 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 (or ones) you need. +#### Message Body (Plain Text) + +The **Message Body (Plain Text)** property is the plain-text version of the email body. + +#### Message Body (HTML) + +The **Message Body (HTML)** property is the HTML version of the email body. ### Attachment {#attachment} In the **Attachment** section, select a microflow variable to attach to the email. +#### Variable + 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" %}} @@ -164,22 +199,31 @@ The **Send Email** activity does not impose its own attachment size limit. The m ## 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. +The **Test Email** tab allows you to 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 **Use Template for Test Email** is 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. + +#### To + +The **To** property is the recipient of the test email. + +#### Subject + +The **Subject** property is the subject line of the test email. + +#### Message Body (Plain Text) + +The **Message Body (Plain Text)** property is the plain-text version of the test email body. -When not selected, you can enter the subject and body directly: +#### Message Body (HTML) -| 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. | +The **Message Body (HTML)** property is the HTML version of the test email body. ### Send Test Email {#send-test-email}