How the Flowable email task sends notifications from a process
A team that needs a process to notify people by email at specific steps should know first that the Email task is a dedicated service task type, not an official BPMN 2.0 task. It sends mail through an SMTP server configured for the Flowable engine, and it does nothing until a valid SMTP configuration exists. Mail server setup is optional for a Flowable deployment, but a process that sends email cannot run without it. The Flowable configuration docs describe the email task alongside the Http, Camel, Shell and External Worker tasks, which are also service task types with Flowable-specific behavior. Each of these changes how the engine performs the work, so the email task belongs to the same family of engine-specific extensions as the others.
Because the email task is a Flowable extension, a model that uses it is tied to the engine that runs it. Any BPMN tool or reviewer who expects only standard BPMN elements will need to know that the task type is Flowable-specific. In the model, the email task sits where a service task would, and it reads its recipient, subject and body from the process context when the step runs. Before design starts, confirm with your Flowable version and configuration docs which mail attributes and expression forms your release supports, and agree with the process owners which steps are allowed to send email at all. Sending from a model is a runtime action, so it is also the point where a mistake in a template or address reaches a real inbox.
The practical question is whether the engine should send the mail at all. The email task suits internal, low-volume notifications triggered by a process step, such as an approval request or a status update, where the process already owns the state. It is a weaker fit for marketing messages, high-volume broadcasts or mail that needs consent tracking, bounce handling and delivery reports. For those, a notification service that the process calls through an HTTP task or an event is usually the better boundary. Ask your team to decide this per message type during design, and confirm with your messaging and security owners where mail credentials are stored and who may change the SMTP settings.
What you need before the email task can send mail
A mail server is optional in Flowable, so teams whose processes never send email can skip this section entirely. Teams that do need email from business processes should confirm the items below first, because most delays come from approvals, network paths and certificates rather than from the BPMN model itself.
Engine version and deployment style
Confirm which Flowable engine version you run and whether it is embedded as a JAR, started through a Spring Boot starter, or deployed as the REST application. The configuration keys for the mail server depend on that choice, so the property names you use must match your version's configuration docs. Check the version against the release notes before you copy any example.
SMTP relay approved by security
Ask your security team which SMTP relay the engine may use, and whether it expects authenticated submission with a service account or an allowlist of sending hosts. Agree in writing who owns the account, how its password or secret is stored, and who rotates it. A relay that only accepts mail from known IP addresses will reject messages from a new host until that host is added.
Network paths from the engine host
Confirm that the hosts running the Flowable engine can reach the relay on the port your security team approved, through any egress firewall, proxy or NAT gateway. Test from the same network segment and container or node pool that will run production, since a test from a laptop proves little about the engine's path. Record the path so the firewall change is repeatable.
TLS certificates and trust stores
Confirm the relay's certificate chain, whether the relay requires STARTTLS or implicit TLS, and whether the engine's Java trust store contains the issuing authority. Private or internal certificate authorities are a common cause of handshake failures, and the fix belongs in the trust store of the runtime image, not in code. Ask who will renew the certificate and how the engine is told about renewal.
A test mailbox and sender identity
Create a dedicated test mailbox and agree on the sender address and display name that processes will use. Confirm with the mail team whether the sender domain has SPF, DKIM and DMARC records that match the relay, because messages from an unaligned sender may be filtered or rejected. Use the test mailbox for every environment before any production recipient receives mail.
Who owns recipients and templates
Decide which team owns the recipient lists, email templates and the business rules that choose a recipient, and who approves changes to them. The engine only sends what the process variables and model define, so these owners should review process definitions that send mail. Agree on what personal data may appear in messages and in history before the first process goes live.
Configuring the SMTP server and the email task step by step
This sequence takes a Flowable engine from no mail settings to a verified email task that sends messages with recipients and content taken from process variables. Each step ends with a check you can see before moving on.
Confirm the mail server is required for your processes
Mail server configuration is optional in Flowable, so the engine starts without it. Before you change anything, your platform team should confirm which processes will send email, which relay they must use, and whether that relay accepts connections from the engine's network segment. Record the relay host, port, transport security mode and whether it requires authentication. You are done when the team has one written list of these values for the test and production environments, and the relay owner has confirmed the sending address is permitted.
Set the SMTP host, port and security in configuration
Add the mail settings to the engine configuration as described in the Flowable configuration documentation. Set the SMTP host, port, transport security and authentication properties for your relay, and take the credentials from your secrets store rather than writing them into a file that is committed to source control. Engineers who own the deployment pipeline make this change, and the platform team reviews it. You know the step is complete when the configuration is merged and the values match the relay record from the previous step.
Start the engine and confirm mail settings load
Start the engine in the test environment and read the startup log for errors related to mail or configuration parsing. Then check that the mail settings reached the engine, for example by confirming the values the process engine reports or by checking the configuration you deployed against the environment. A startup failure at this point usually means a property name or value is wrong, so fix the configuration rather than changing the model. The check passes when the engine starts cleanly and the mail values match what you set.
Add a fixed Email task to a test model
Create a small BPMN test model with a start event, an Email service task and an end event. The Email task is one of the dedicated service task types that Flowable provides, not a standard BPMN 2.0 task. Set a fixed recipient address that your team controls, a fixed subject and a short plain-text body. Keep the model free of other logic so that any failure points to the mail configuration. You know the model is ready when it deploys without validation errors and appears in the engine's deployed definitions.
Run the test process against a test relay
Point the test environment at a test relay or a mailbox trap that holds messages without delivering them outside the organization. Start one instance of the test process and let it run to the end event. Check the engine log for the send operation and confirm there are no exceptions. The check passes when the message appears in the test mailbox or relay log. If nothing arrives, look first at the relay logs, then at the authentication and transport security settings.
Verify headers, encoding and sender identity
Open the received message and inspect its headers, not only the visible content. Confirm the From address, the To address, the subject line, the character encoding and the content type match the model and the relay policy. Check that the message passes the relay's sender authentication checks, such as the mechanisms your domain uses, and that it does not land in a spam folder. Record the headers as a reference sample for later comparison. You are done when a reviewer on the mail or security side agrees the headers are acceptable.
Parameterize recipients and content from variables
Replace the fixed recipient, subject and body with expressions that read process variables, so each instance sends to its own customer or approver. Set the variables when the process starts or in an earlier task, and validate them before the Email task runs, since a blank recipient causes a send failure. Run the process again with two different variable sets and confirm each message goes to the correct recipient with the correct content. The step is complete when both test runs produce the expected messages and the logs show no unresolved expressions.
How recipients, subjects and bodies come from process variables
The email task does not hold its own message content. Its recipient, subject, body and other fields are expressions that resolve against process variables at the moment the task runs, so the values are set by earlier service tasks, user task forms, the start payload or a script. The practical consequence is that every email is only as correct as the variables it reads, and the model should show where each one is set. Before you build, list each field the email task needs, name the variable that supplies it, and identify which step writes that variable. Confirm in the Flowable BPMN documentation for your engine version exactly which email task attributes accept expressions and which are fixed text, because this varies by attribute.
Three failure modes deserve design attention. An expression that does not resolve can leave literal placeholder text in a message or fail the step, depending on how the variable is referenced, so test with missing and empty values, not only the happy path. A missing variable can stop the step entirely, which then becomes a failed job that needs handling. A list-valued variable used as a recipient needs a defined format for multiple addresses, and you should test that format with the mail server you actually use. Also confirm how the engine handles character encoding for non-ASCII names and how it treats HTML in the body, since an unescaped value from a form can inject markup into a message. Confirm which template or text-formatting options your engine version supports before you rely on them.
Keep personal data in process variables limited to what the message needs. A variable that carries a full customer record will be stored in process history and may be visible to anyone with access to the engine's data, so pass only the name, the reference number or the status the message requires, and resolve anything else from the system of record when the email is sent. Ask your privacy and security teams which variable names and history settings they need to review, and confirm with them whether email content should be retained in history at all. Clear decisions on these points are cheaper to make at design time than after a process has run in production.
Mapping process variables to email fields
This table lists each email task field, the process variable or expression that usually supplies it, the type it should carry, the team that owns the data, and the fallback to use when the value is empty. Read it as a checklist for the model review: any field without a named owner or fallback is a likely source of mis-sent or blank emails. Confirm the exact field names and supported options in the Flowable docs for your deployed version before you build against them.
| Email field | Source and expected type | Owning team | Fallback if empty |
|---|---|---|---|
| Sender (from) | Configured default or a string variable such as senderAddress, expected to be one valid address | Platform team, with the messaging team for allowed domains | Use the configured default sender, never a user-supplied value |
| Recipients (to) | String or comma-separated list of addresses, resolved from a process variable | Business process owner, with the data owner for contact records | Route to a fallback mailbox or a user task instead of sending to nobody |
| Carbon copy (cc) | Optional list of addresses from a variable, often empty by design | Business process owner | Omit the field entirely when the variable is null or empty |
| Subject | Short string built from a variable, such as an order reference, kept within agreed length | Process designer, reviewed by the business owner | Use a fixed subject that names the process so the message is still traceable |
| Body text | Plain text string, expression or variable holding rendered content | Process designer and the owner of the message wording | Use a standard default paragraph and log that the template variable was missing |
| HTML body | HTML string from a variable, reviewed for escaping of user-entered values | Process designer and security team | Fall back to the plain text body and do not send unescaped user input as markup |
| Attachments | Reference to a file or variable pointing to stored content, confirmed against the docs for your version | Document owner and security team | Send without the attachment only when the process allows it, and record the omission |
Handling failed sends with async retries
A temporary SMTP outage, such as a relay that is restarting or a network path that drops for a few minutes, is the case retries are designed for. When the email task runs as part of an asynchronous step, the send is packaged as a job. The async executor runs jobs from a thread pool, and when a job throws an exception, the job system schedules it again instead of losing the message. Retry count and the wait between attempts are set in the engine configuration, so confirm the values your team agrees with the mail operations group before go-live.
- Job-based retry: A failed send becomes a job that the executor picks up again, so the process does not stop at the email step.
- Retry settings: The number of attempts and the interval between them are configuration choices, not defaults to assume.
- Recovery after restart: Jobs are stored in the database, so a node restart does not discard a pending send.
- Outage length: Retries only succeed if the outage ends within the retry window, so long outages move jobs to the failed list.
- Relay capacity: Retry bursts after an outage can add load on the relay, so plan for a backlog to drain gradually.
Before relying on this path, test a deliberate relay shutdown in a non-production environment and confirm that the job count and retry timing match what your operators expect.
A rejected recipient, such as an address the receiving server refuses as unknown or a mailbox that is full, is a permanent or near-permanent failure. Retrying the same message against the same address rarely changes the result, so repeated attempts only consume job capacity and delay the operator who needs to fix the data. The right response is to make the failure visible and to decide, in the process design, what happens to the case next.
- Permanent versus temporary rejections: Ask the mail team how the relay signals each class, since the engine treats them as the same exception unless your code separates them.
- Bad data at the source: Validate recipient fields when the process starts or when the variable is set, so malformed addresses never reach the send.
- Failed job visibility: After repeated failures, the job appears in the failed job list where an operator can inspect the recipient and retry or act.
- Process branching: Where a notice is required, model a path that routes the case to a manual task instead of waiting on an email that will not arrive.
- Logging: Record the recipient reference and the rejection text in your logs, while keeping personal data to what your privacy policy allows.
Confirm which failures your team classifies as permanent and whether any of them should trigger a business step rather than a retry.
A misconfigured credential, such as an expired SMTP password, a wrong username, or a TLS setting the relay rejects, fails every send in the same way. Retries cannot fix this and will fill the failed job list quickly. Treat this as a configuration incident: the engine's job state shows the problem, but the fix happens in the configuration or the secret store, and the stalled jobs must be retried afterward.
- Uniform failures: A sudden spike of failed email jobs with the same authentication error points to credentials rather than recipients or outages.
- Secret source: Confirm where the SMTP password is read from and who rotates it, so a rotation does not silently break sends.
- Restart requirements: Check whether a configuration change needs an engine restart to take effect before retrying failed jobs.
- Alerting: Alert on the failed job count for the email step so the problem is caught before users notice missing messages.
- Recovery order: Fix the credential first, verify with one test message, then retry the failed jobs in controlled batches.
Before go-live, confirm the alert threshold, the secret rotation owner, and the runbook steps with the team that operates the mail relay.
Marking the email step as asynchronous is the setting that enables retries, and it also changes the risk profile. If the engine cannot confirm that the relay accepted a message, for example because the connection drops after the message was sent but before the reply arrived, the job may be retried and the recipient may receive the same email twice. Duplicate sends are a normal property of at-least-once job processing, not a defect to hope away, so the decision needs an owner before the step is switched on.
- Confirm the semantics: Ask the engine documentation and your own tests how a retried send is treated, and whether any deduplication exists for your configuration.
- Idempotent content: Design messages so that a second copy is harmless, for example by including a reference that lets recipients recognize a repeat.
- Business impact: Identify which emails are dangerous to duplicate, such as payment or legal notices, and handle those with extra checks.
- Test the failure: Simulate a dropped connection after submission in a test environment and count the messages received.
- Ownership: Record who approves async email steps and who monitors the failed job list after release.
Before marking the step asynchronous, confirm the duplicate-send behavior with your own test results and record the decision in the process design.
Securing SMTP credentials and outbound email
Email from a Flowable process leaves your engine and reaches people outside your network, so the credentials, transport, content and sender identity all need controls. The cards below cover what to protect, how to limit who can send, and what to confirm with your mail team before the first production send.
Keep SMTP credentials out of models
The SMTP username and password should not appear in BPMN files, process variables, or source control. Put them in your deployment's secret store or environment configuration and reference them from the engine configuration at runtime. Check that exported models, logs and history data do not echo the credential values, and that the relay account has only the send permission it needs. Confirm the rotation process with the team that owns the mail relay.
Encrypt the relay connection
Configure the connection to the SMTP relay to use TLS so that credentials and message content are not sent in clear text across the network. Confirm with the mail team which mode the relay supports and whether certificate validation is enforced on the Flowable side. Treat any plaintext option as a documented exception that needs a named owner and a review date.
Restrict who can send and where
Not every process should be able to send email. Decide which process definitions may use the email task, and agree a list of permitted recipient domains with the business owners. Enforce the allowlist in the model design or in a delegate that validates recipients before the send, because the email task itself does not apply your policy. Review changes to this list as part of the normal process change control.
Limit sensitive content in bodies
Email bodies often end up in mailboxes, forwarding chains and archives outside the process owner's control. Use notifications that point to a secured task or record instead of copying personal data, account details or case findings into the message. Ask your privacy and records teams to confirm which fields may appear in a body and how long copies persist on the recipient side.
Keep an audit trail of sends
Record which process instance sent which message, to whom, and when, so that support and compliance staff can answer delivery questions. Use the engine history for the send step and capture relay responses for failures, while keeping message bodies out of logs where your policy requires it. Confirm retention periods for these records with your compliance team, since they may also contain personal data.
Confirm sender authentication with mail
Messages sent for your organization should pass the sender checks your recipients rely on. Ask the mail team to confirm the SPF record for the sending addresses, the DKIM signing configuration for the relay, and the DMARC policy published for the domain. Agree which sending domain and envelope address the Flowable notifications will use before testing, so that the production configuration matches what was validated.
Common email task failures and how to fix them
This table lists the failures teams most often hit with the Flowable email task, with the likely cause and the fix for each. Read it when a notification does not arrive, arrives twice, or stops the process, and start with the first row if the engine has no mail server configured. Most failures trace back to SMTP settings, expression values or sender DNS records rather than the process model itself.
| Failure | Likely cause | Fix |
|---|---|---|
| Email step fails after engine start | No valid SMTP server configuration is present, so the email task has nothing to send through | Add a valid mail server configuration as described in the configuration docs, then confirm the failing job runs on restart |
| Connection refused or timeout | Wrong host or port, or the relay is only reachable from certain network segments | Confirm the relay host and port with the mail team and test reachability from the exact node running the async executor |
| Handshake or certificate error | TLS mode does not match the relay (for example, STARTTLS expected but plain SSL configured, or the certificate chain is not trusted) | Agree the TLS mode with the relay owner, set it explicitly, and import the relay's CA into the Java truststore if needed |
| Authentication rejected by relay | Username, password or auth mechanism differs from what the relay requires, or the password was rotated without updating the secret | Store credentials in your secrets manager, confirm the account is allowed to relay from the engine's address, and check the relay log for the rejection reason |
| Recipient is empty or literal expression text | A process variable used in the recipient expression is unset, null or not the expected type at runtime | Validate required variables before the email task, set defaults, and add a test that starts an instance with missing data |
| Mail lands in spam or is rejected | Sending domain lacks SPF, DKIM or DMARC records, or the envelope sender does not match the domain | Work with the domain owner to publish sender records and align the From address with the authorized relay |
| Duplicate messages after a retry | The mail was accepted by the relay, but the job failed or timed out before completion was recorded, so the async retry sent it again | Make the email step idempotent where possible, shorten retry windows, and check relay logs before resending manually |
| Jobs stuck in the failed list | Retries are exhausted or the underlying SMTP error persists, so the job stays failed | Review failed jobs, fix the root cause, then retry; see the Flowable operations and troubleshooting guidance for failed jobs and retries |
When to hand email to a notification service instead
Keep the Flowable email task for transactional messages that belong to a single process step, such as an approval request or a status notice tied to one instance. Hand email to a dedicated notification service when the volume, the consent rules or the number of applications sending mail make the process engine the wrong owner of delivery. Typical triggers are high send volumes, marketing or consent-managed campaigns, per-channel preferences that a user can change, delivery tracking and bounce handling across email, SMS and push, and notification logic shared by many applications. In those cases, a marketing automation tool such as Mautic may suit campaign work better, and a notification platform may suit cross-channel delivery. Confirm with the owners of those systems which one already holds consent records and suppression lists before you build a second path.
The split that works is to keep the process as the trigger and the service as the delivery owner. The BPMN model decides that a notification is due and passes the recipient, the template key and the business identifiers as process variables. A Flowable HTTP task can call the service's send API, or an external worker can pick up a job and make the call from a service in any language. Set the variable mapping and the timeouts deliberately, and decide whether the process waits for an accepted response or only for a queued message. Store the service's message identifier in a process variable so that a later delivery failure can be traced back to the instance.
Before you commit to this design, agree on ownership of failures and status. The notification service should report delivery and bounce events, and the process should not assume a message was delivered just because the API call succeeded. Ask the team that runs the service for its retry policy, its rate limits, its data retention for recipient details, and how it handles unsubscribe requests. Also confirm where personal data in process variables is kept, because the engine's history stores them unless you configure otherwise. A short written contract covering these points is usually more useful than a long architecture discussion.
Questions teams ask before setting up Flowable email
What does the Flowable email task setup effort depend on?
The effort depends on four things: how many email templates you need, how much access you can get to the SMTP relay, how much security review the sending path requires, and how retries and failure handling are designed. A single relay with a handful of templates is a small job. Each additional template adds content, variable mapping and testing, and each review gate adds calendar time. Ask any partner to price the scope against these four drivers in writing rather than against a single number.
Can our own team configure Flowable email without outside help?
Yes, for a single relay and a few templates, a capable Java team can usually do the work alone. The SMTP settings are documented in the Flowable configuration docs, and the email task is a dedicated service task type in the BPMN model. Use a test relay or a sandbox mailbox first so you can check recipients, templates and failures without sending mail to real customers. Bring in outside help when you need a formal security review, multiple relays, or async retry design that must be tested under load.
How long does an email setup take?
Duration depends mostly on approvals and environments, not on the Flowable configuration itself. Sender domain changes, relay onboarding, security sign-off and the promotion path from test to production often take longer than the code. We do not publish timelines for this work. Ask for a written scope that lists the environments, approval steps and test cycles, and confirm with your change board how long each step usually takes in your organization.
What does our team need to provide for the email work?
Plan to provide relay credentials through your secrets process, DNS access or a change request for the sender domain's SPF, DKIM and DMARC records, a test mailbox that your team can read, and named owners for each process variable used in templates. Variable owners matter because a template that expects a customer name or a case number breaks silently when the upstream process changes. Confirm with your mail team who approves relay access and who can publish DNS records before work starts.
Do we need a notification service instead of the email task?
Not always. The email task works well for internal approvals, process reminders and occasional customer messages sent from a process step. Consider a dedicated notification service when you need channel fan-out to SMS or push, preference and consent management, high volume bulk mail, or delivery analytics maintained by a separate team. A notification service can also keep relay credentials and sender reputation out of the process engine. Decide this before building templates, because moving later changes the integration and the variables passed to it.
How do Flowable versions affect email configuration?
The SMTP configuration and the email task are part of the engine, so version changes can affect how you wire them into your application. Flowable 8.0.0, released on February 27, 2026, requires Spring Boot 4 and Spring Framework 7, and it does not support Spring Boot 3. If you are on Spring Boot 3, plan the framework upgrade before or alongside the email work and retest the mail path after the upgrade. Confirm the exact property names and dependency coordinates against the documentation for your release.
How should we handle failed emails in a running process?
Treat email as an asynchronous step with a defined retry policy. Configure the email task so a transient relay failure leads to a retry rather than a stuck instance, and set a final failure path that records the error and notifies an owner. Keep recipient and template variables in the process so a retry resends the same content. Confirm how your Flowable version exposes failed jobs and retry counts, and test a relay outage in your test environment before production go-live.
How DeployOpen works on this
DeployOpen plans, implements, customizes, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure. For the Flowable email task, that means agreeing the SMTP setup, the templates and the failure handling in writing before any process model is changed.
How we scope
- Inventory which processes send email, which recipients they reach and which mail domains must be authorized.
- Confirm the SMTP relay, TLS and authentication requirements with your mail team before configuration starts.
- Agree in writing how failed sends are retried, logged and escalated, and what happens to the process when delivery fails.
How we build
- Configure the SMTP server settings for the Flowable engine in the environment you control, with secrets kept out of model files.
- Build email tasks with recipients and templates taken from process variables, and test each template with sample data.
- Test failure paths with a deliberately unreachable mail server, confirming async retries and the outcome recorded in history.
How we hand over
- Document the SMTP configuration keys, environment variables, and the owners of each mail account and sender address.
- Provide a runbook for diagnosing failed email jobs, including where retries appear and how to reprocess them.
- Deliver a decision record stating which emails stay in Flowable and which move to a notification service, with reasons.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer, including checks after Flowable version upgrades.
- Ask us to confirm the mail-related settings and behavior for your exact Flowable version before you rely on them in production.
