Skip to content

Commit 0e917ad

Browse files
quinntracyquinntracy
authored
Merge pull request #11542 from atul-lahade-mx/development
[ADCP-25] Send Email Action (Beta)
2 parents 00a9229 + 1731834 commit 0e917ad

4 files changed

Lines changed: 304 additions & 0 deletions

File tree

‎content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/_index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,16 @@ These activities can only be used in microflows.
122122
| {{< 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. |
123123
| {{< 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. |
124124

125+
## Email Activities
126+
127+
{{% alert color="info" %}}
128+
These activities can only be used in microflows.
129+
{{% /alert %}}
130+
131+
| Graphic | Name | Description |
132+
| --- | --- | --- |
133+
| {{< 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. |
134+
125135
## ML Kit Activities
126136

127137
[ML Kit activities](/refguide/ml-kit-activities/) are used with a machine learning model.

‎content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/_index.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: "Email Activities"
3+
url: /refguide/email-activities/
4+
weight: 82
5+
---
6+
7+
{{% alert color="info" %}}
8+
These activities can only be used in microflows.
9+
{{% /alert %}}
10+
11+
## Introduction
12+
13+
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.
14+
15+
The following are the Email activities you can use in your microflow:
16+
17+
- [Send Email](/refguide/send-email-action/)

‎content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/email-activities/send-email-action.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
---
2+
title: "Send Email"
3+
url: /refguide/send-email-action/
4+
weight: 20
5+
description: "Describes how to use the Send Email microflow activity to send emails directly from a microflow in Studio Pro."
6+
#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.
7+
---
8+
9+
## Introduction
10+
11+
The **Send Email** activity allows you to send an email directly from a microflow. Within a single activity, you configure the following:
12+
13+
* Email server connection
14+
* Authentication method
15+
* Sender and recipients
16+
* Message content
17+
* Attachments
18+
19+
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.
20+
21+
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.
22+
23+
{{% alert color="warning" %}}
24+
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).
25+
{{% /alert %}}
26+
27+
## Properties
28+
29+
Double-click the **Send Email** activity to open its dialog box. The dialog box is organized into the following tabs:
30+
31+
* [General](#general) – configure the sender, the security method, and the server connection
32+
* [Message](#message) – configure the recipients, custom headers, message body, and attachment
33+
* [Test Email](#test-email) – send a test email to verify your configuration
34+
35+
## General Tab {#general}
36+
37+
The **General** tab configures how Studio Pro connects and authenticates to the email (SMTP) server, and which address the email is sent from.
38+
39+
### Sender's Details {#senders-details}
40+
41+
#### Email ID (From)
42+
43+
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/).
44+
45+
{{% alert color="info" %}}
46+
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.
47+
{{% /alert %}}
48+
49+
### Security Method {#security-method}
50+
51+
The **Security method** section determines how the connection authenticates to the email server. The connection uses basic authentication.
52+
53+
{{% alert color="warning" %}}
54+
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:
55+
* Re-enable SMTP basic authentication for the account (where your administrator's policy allows it), or
56+
* Use a provider that supports basic SMTP authentication.
57+
{{% /alert %}}
58+
59+
#### Username
60+
61+
The **Username** property is the username used to authenticate to the email server.
62+
63+
#### Password
64+
65+
The **Password** property is the password used to authenticate to the email server.
66+
67+
{{% alert color="warning" %}}
68+
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.
69+
{{% /alert %}}
70+
71+
### Connection {#connection}
72+
73+
The **Connection** field configures how Studio Pro reaches the email server.
74+
75+
{{% alert color="info" %}}
76+
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.
77+
{{% /alert %}}
78+
79+
#### Email Protocol
80+
81+
The **Email Protocol** property is the protocol used to send email. This property is read-only.
82+
83+
Default value: *SMTP*
84+
85+
#### Security Type
86+
87+
The **Security Type** property is the transport security used for the connection: **None**, **SSL**, or **TLS**.
88+
89+
Default value: *TLS*
90+
91+
#### Check Server Identity
92+
93+
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**.
94+
95+
Default value: *No*
96+
97+
#### Timeout (ms)
98+
99+
The connection timeout (in milliseconds).
100+
101+
Default value: *20000*
102+
103+
#### Server Host
104+
105+
The **Server Host** property is the address of the email (SMTP) server.
106+
107+
#### Server Port
108+
109+
The **Server Port** property is the port of the email (SMTP) server.
110+
111+
### Test Connection {#test-connection}
112+
113+
Click **Test Connection** to verify the configured connection and authentication settings are valid.
114+
115+
{{% alert color="info" %}}
116+
**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.
117+
{{% /alert %}}
118+
119+
## Message Tab {#message}
120+
121+
The **Message** tab configures the recipients, custom headers, message content, and attachment.
122+
123+
### Receiver's Details {#receivers-details}
124+
125+
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.
126+
127+
#### To
128+
129+
The **To** field is the primary recipient (or recipients) of the email.
130+
131+
#### Cc
132+
133+
The **Cc** field is the carbon-copy recipient (or recipients) of the email.
134+
135+
#### Bcc
136+
137+
The **Bcc** field is the blind carbon-copy recipient (or recipients) of the email.
138+
139+
### Custom Headers {#custom-headers}
140+
141+
The **Custom headers** section allows you to add custom email headers. Use the toolbar to manage headers:
142+
143+
* **Add** – add a new custom header
144+
* **Edit** – edit the selected custom header
145+
* **Delete** – remove the selected custom header
146+
147+
#### Name
148+
149+
The **Name** property is the name of the header. This can only contain letters, digits, and hyphens, and cannot be empty.
150+
151+
#### Value
152+
153+
The **Value** property is the value of the header. It cannot be empty or contain line breaks.
154+
155+
### Message Body {#message-body}
156+
157+
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:
158+
159+
```text
160+
Subject: "Order {1} confirmed"
161+
{1} → $Order/OrderNumber
162+
163+
Body: "Hi {1}, your order ships on {2}."
164+
{1} → $Order/Customer/FirstName
165+
{2} → formatDateTime($Order/ShipDate, 'yyyy-MM-dd')
166+
```
167+
168+
{{% alert color="info" %}}
169+
Consider the following about templates:
170+
* 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.
171+
* Keep placeholder numbering contiguous (`{1}`, `{2}`, …), and make sure every placeholder has a corresponding parameter expression.
172+
* 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.
173+
* The HTML and plain-text bodies are independent. Populate only the one (or ones) you need.
174+
{{% /alert %}}
175+
176+
#### Subject
177+
178+
The **Subject** property is the subject line of the email.
179+
180+
#### Message Body (Plain Text)
181+
182+
The **Message Body (Plain Text)** property is the plain-text version of the email body.
183+
184+
#### Message Body (HTML)
185+
186+
The **Message Body (HTML)** property is the HTML version of the email body.
187+
188+
### Attachment {#attachment}
189+
190+
In the **Attachment** section, select a microflow variable to attach to the email.
191+
192+
#### Variable
193+
194+
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).
195+
196+
{{% alert color="info" %}}
197+
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.
198+
{{% /alert %}}
199+
200+
## Test Email Tab {#test-email}
201+
202+
The **Test Email** tab allows you to send a test email to verify your configuration from Studio Pro without triggering the microflow.
203+
204+
### Test Email Details {#test-email-details}
205+
206+
#### Use Template for Test Email
207+
208+
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.
209+
210+
When not selected, you can enter the subject and body directly.
211+
212+
#### To
213+
214+
The **To** property is the recipient of the test email.
215+
216+
#### Subject
217+
218+
The **Subject** property is the subject line of the test email.
219+
220+
#### Message Body (Plain Text)
221+
222+
The **Message Body (Plain Text)** property is the plain-text version of the test email body.
223+
224+
#### Message Body (HTML)
225+
226+
The **Message Body (HTML)** property is the HTML version of the test email body.
227+
228+
### Send Test Email {#send-test-email}
229+
230+
Click **Send Test Email** to send the test email using the current configuration. A message indicates whether the test email was sent successfully.
231+
232+
{{% alert color="info" %}}
233+
**Send Test Email** is only enabled when your app is running and the **To** field is provided.
234+
{{% /alert %}}
235+
236+
## Error Handling {#error-handling}
237+
238+
Sending emails can fail at runtime for reasons outside your app's control, such as:
239+
240+
* The email server is unreachable
241+
* The connection times out
242+
* Authentication is rejected
243+
* A recipient address is invalid
244+
245+
When this happens, the **Send Email** activity raises and logs an error.
246+
247+
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.
248+
249+
## Before Going to Production {#production}
250+
251+
Review the following before you deploy to a production app.
252+
253+
### Authentication and Credentials
254+
255+
- 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.
256+
- 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.
257+
258+
### Email Deliverability (SPF, DKIM, and DMARC)
259+
260+
The sending domain must be configured correctly at the DNS level for your emails to be accepted and not marked as spam.
261+
262+
- **SPF** – authorizes which servers may send emails for your domain
263+
- **DKIM** – cryptographically signs your messages so recipients can verify they were not altered
264+
- **DMARC** – tells receiving servers how to handle messages that fail SPF or DKIM checks
265+
266+
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.
267+
268+
{{% alert color="info" %}}
269+
When deploying to Mendix Cloud, refer to [Sending Email](/developerportal/deploy/sending-email/) for supported providers and SMTP configuration guidance.
270+
{{% /alert %}}
271+
272+
## Read More
273+
274+
- [Sending Email](/developerportal/deploy/sending-email/) – external email providers and SMTP configuration for Mendix Cloud
275+
- [Error Handling in Microflows](/refguide/error-handling-in-microflows/)
276+
- [Constants](/refguide/constants/)
277+
- [Microflow Expressions](/refguide/expressions/)

‎static/attachments/refguide/modeling/application-logic/microflows-and-nanoflows/activities/send-email.png‎

1.85 KB
Loading

0 commit comments

Comments
 (0)