Email
This page is for administrators. It covers how TaskFlow sends email: password resets, notifications, Service Desk replies to customers and mail sent by automation rules.
How email works here
TaskFlow has no mail settings of its own and no built-in SMTP client. Sending is done by a transport — a feature you enable, fill in with your provider's credentials, and then assign to the kinds of mail it should carry.
That means two steps, and both are needed before anything is delivered:
- Enable and configure a transport.
- Assign it to a purpose — otherwise mail of that kind simply isn't sent.
There is no fallback
If no transport is assigned to a purpose, mail of that purpose is not delivered — it doesn't quietly go out through some other transport. The attempt is still recorded in the delivery log with a "failed" result and the MAIL_NOT_CONFIGURED code, so the gap is visible rather than silent. This is deliberate: which provider carries your mail is an administrator's decision, not something the system should guess.
Mail is sent through a queue: usually within a fraction of a second, but if the provider is busy or unreachable the message isn't lost — it waits and goes out later. What an administrator sees meanwhile is covered in Outgoing queue.
Available transports
| Transport | Sends through | Notes |
|---|---|---|
| SMTP | Any mail server over SMTP: a corporate Exchange, Postfix, your hosting provider's mail, an internal relay | The universal option for your own infrastructure. Needs port 587, 465 or 25 open. |
| JMAP | A JMAP server: Stalwart, Fastmail, Cyrus | The channel runs over 443 — no SMTP ports needed. A copy of each message stays in Sent on the server. The only transport that can also receive mail — see Receiving mail. |
| AWS SES | Amazon SES | Full support, including threading. |
| SendGrid | SendGrid Mail Send API | Full support. |
| Google Workspace | Gmail API, as a user of your Workspace domain | Requires domain-wide delegation to be set up on the Google side. |
| Platform gateway | The platform's mail gateway | Your instance holds no provider keys. The default for instances provisioned by the platform. Does not support copies (cc) or threading, and is subject to quotas. |
Transports are not mutually exclusive — you can run several at once and route different mail through different providers. No transport supports message attachments — the product's mail API doesn't carry them.
Which one to pick
You have your own mail server — SMTP: it works with anything. Your server speaks JMAP (Stalwart, say), or your provider blocks SMTP ports — JMAP. Your mail lives in a cloud — that cloud's transport. The instance was provisioned by the platform — the platform gateway is already set up and needs nothing.
Each transport declares honestly what it can do, and TaskFlow drops the fields it can't handle rather than failing: a message goes out without a copy or without being threaded, instead of not going out at all.
Setting up a transport
- Make sure the transport is permitted by your instance's configuration and enable it under Administration → Plugins (see Plugins).
- Open Administration → Email and pick the transport from the nested menu.
- Enter the provider's credentials on its page. Credentials live here, in the interface — there are no environment variables for them.
- Press Check connection: the transport verifies access, encryption and the right to send from the given address, without sending anything.
- Send a test message to confirm the provider accepts it.
- Assign the transport to at least one purpose — otherwise it is configured but carries nothing. The page says so plainly.
Passwords and keys are never handed back: once saved, the field only shows that a value is set. Leaving a password field empty when saving again means “keep the current one”.
What SMTP asks for
| Field | What it sets |
|---|---|
| Server, Port | The mail server host without a scheme, and the port: 465 for implicit TLS, 587 or 25 for STARTTLS. |
| Encryption | STARTTLS, implicit TLS, or none. None is acceptable only inside your own network: the password travels in clear text. |
| Username, Password | Credentials. Empty — the server accepts mail without authentication (an internal relay). |
| Sender address, Sender name | Who the mail comes from. The server must allow sending from that address. |
| EHLO name | Optional; empty means the sender address's domain. Some servers require a fully qualified name. |
| Do not verify the certificate | Only for an internal server with a self-signed certificate. On the internet it is a hole. |
What JMAP asks for
| Field | What it sets |
|---|---|
| Server address | https://mail.example.com, for instance. No path needed — the transport discovers the entry point itself. |
| Entry point (override) | Usually empty. Fill it in only if the server sits behind a proxy and announces an address that does not work from outside: the connection check then fails on the certificate or returns 404. |
| Username, App password | An app password rather than the mailbox password: it can be revoked without touching the others. |
| Sender address, Sender name | The address must be allowed for that account on the server. |
The platform gateway is the exception
On the platform gateway page the address and token fields are usually empty, and that's normal: they are handed to the instance when it is provisioned. Fill them in only to override what was handed over — when moving an instance, or while debugging. The page shows which address is actually in use and where it came from.
Send-rate limits
The platform gateway page also sets its own limits — how many messages the instance sends per minute and per day (0 means no limit). These are not a copy of the platform's quotas but protection against them: exceeding a platform quota means a lost message, so the instance keeps its own lower limit and paces a batch out over time instead of running into a refusal.
In practice:
- sending one message out of a large batch can take a few seconds — that's expected, and the message still goes out;
- a limit set too low (a couple of messages per minute) does the opposite: the wait exceeds what's allowed and messages start failing with a rate error;
- the windows are sliding — the last 60 seconds and the last 24 hours, with no spike at midnight. The page shows how much was sent in both windows.
Bulk mailing isn't done through this channel: the gateway has no copies and no threading, and one message has a capped number of recipients.
Platform limits on a cloud instance
A cloud instance may be given a mailbox on the platform's own mail server — mail is then sent directly by the SMTP or JMAP transport, with a copy in Sent and with the threading the gateway lacks. JMAP arrives with the credentials already filled in; SMTP is filled in by the administrator.
How much you may send is shown in the Platform limits block on the transport's page: per day, per minute, recipients per message, and how many have gone out today. These numbers can't be edited in the interface — they follow your plan and the number of paid seats.
Your own mail is not capped
The limit applies only to the mailbox granted by the platform. Point the transport at your own mail server and the platform neither counts nor caps that mail. A self-hosted installation has no such block. Gateway limits and direct-send limits are separate channels and do not add up.
A message that hits the cap isn't lost — it waits in the queue and goes out once the limit lifts. Two refusals are not cured by waiting, so they are marked as an error in the log straight away instead of occupying the queue: the channel switched off by the platform, and a message addressed to more recipients than the plan allows. Split the recipients or send them separately.
Assigning transports to purposes
Mail is grouped by purpose, and each purpose is assigned a transport separately:
| Purpose | Covers | Assigned on |
|---|---|---|
| System | Password resets and other account mail. | Administration → Settings |
| Notifications | Notification emails about issues you're involved in. | Administration → Notification gateways |
| Service Desk | Replies sent to a customer when an agent answers their request. | Administration → Service Desk |
| Automation | Mail sent by the Send email action in a rule. | Administration → Automation |
Each purpose is assigned where its feature is configured, rather than all in one list. The overall picture — which transport serves which purpose — is on Administration → Email.
Purpose priority
On Administration → Email, each purpose has a Queue priority — whose mail goes out first when a lot of it has piled up. Lower goes first; the defaults are:
| Purpose | Default priority |
|---|---|
| System | 10 |
| Notifications | 20 |
| Service Desk | 30 |
| Automation | 40 |
Worth adjusting if your provider only lets a few messages through per minute: then a password-reset link should overtake a batch of notifications, and a bulk mailout from a rule should go last. While mail volume is low, priority changes nothing. A new value applies to new mail — messages already waiting keep their place.
Receiving mail: a request from an email
Everything above is outgoing mail. The JMAP transport also does the reverse: a message arriving at an address in your domain becomes an event, and automation rules take it from there — create a request, append a comment to an existing one, send it to quarantine.
The rule decides, not the mailbox
The product deliberately carries no hard-wired “email → request” scenario: support teams do it differently. Receiving delivers the message to your rule with every signal attached (who sent it, whether authenticity checks passed, whether it is spam, whether it is a reply in a thread), and the rest is up to you.
What you need
- The JMAP feature enabled and configured (you may also use it for sending — the two are independent).
- A separate intake mailbox on the mail server: not the one you send from. The intake account has no right to send mail — which is exactly why its password can live in the instance settings.
- The mail server routes mail addressed to the instance's domain into that mailbox and verifies sender authenticity (SPF, DKIM, DMARC).
- The instance has a public address set: without it the mail server cannot notify it about new messages.
Setting it up
The Receiving mail block is on Admin → Mail → JMAP:
| Field | What it sets |
|---|---|
| Receive mail | The switch. Turning it off erases no log and touches no mailbox — the instance simply stops reading it. |
| Server address | The mail server hosting the intake mailbox. |
| Intake mailbox, Intake password | The account whose mail is processed. |
| Apply now | Creates the service webhook, creates or renews the notification subscription and fetches new mail immediately. |
Below that the block shows the address for the mail server and the state of the subscription — the date it runs until, the last poll and the last message — plus a Recent messages log: sender, subject, check results (spam, auto-reply, unmarked) and whether an event was produced.
The mail server's notification arrives through an inbound webhook — it is visible in Admin → Webhooks marked with its owner. The mail feature has no public address of its own: that is a product-wide rule.
The notification subscription lives for a week
It renews itself, but if the date on screen is in the past, receiving goes silent without an error: messages simply stop reaching your rules. That is the key number in this block — check it first when “requests from email stopped appearing”. Apply now restores the subscription.
A safety net against missed mail
Even without notifications the mailbox is re-read on a schedule, so a one-off network glitch or a restart loses nothing. Mail is looked for across the whole mailbox rather than the inbox alone: a message from a new sender often lands in spam, and a robot reading only the inbox would lose requests silently.
What the rule sees
The event carries: the sender and their domain, the recipient address (including a token in an address like support+abc@…), the subject, the message text, the DMARC, SPF and DKIM verdicts, the “landed in spam” and “auto-reply or bulk” flags, List-Id, Message-ID, In-Reply-To and the attachment count.
The ready-made rule templates cover three typical scenarios: issue from a customer email, customer reply into the thread and email quarantine.
What the message does not bring
Attachment files are not carried into the issue — a rule only gets their count. Spam is not dropped on arrival but flagged: the rule decides, otherwise the losses would be silent. And a message that failed authenticity checks is no reason to trust its sender address — that is trivially forged, so rely on the DMARC verdict in your rules, not on the domain alone.
Outgoing queue
The Outgoing queue block on Administration → Email shows the messages still waiting to be sent. It's the first place to look when a message hasn't arrived: the log below tells you what already happened, the queue tells you what's going on right now.
For every message you see its priority and purpose, who it goes to and with what subject, its state (“waiting” or “sending”), how many attempts were made and when the next one is due. If an attempt failed, the reason is shown under the subject — that's what tells you whether to fix a setting or simply wait.
Two buttons per row:
- Send now — try immediately instead of waiting for the scheduled time. Use it once you've corrected the transport's settings or sorted things out with the provider.
- Drop — remove the message from the queue; it will not be delivered. Asks for confirmation.
How long a message waits
- The provider is busy, unreachable or asks you to wait — attempts repeat by themselves, with the pause growing from half a minute to ten minutes. Nothing to do.
- The provider refuses outright — wrong credentials, a rejected address, no transport assigned: retrying is pointless, so the message is marked failed in the delivery log straight away. That one is fixed in the settings.
- The message waited a day — it is dropped: delivering a reminder about yesterday's deadline no longer helps.
Messages go out one after another, so a large batch is spread over time — that's normal. Only what's waiting stays in the block: sent and failed messages are in the delivery log.
When a provider throttles you
If the provider answers “too often”, the pause is taken for the whole transport — for every kind of mail it carries. Mail assigned to other transports keeps going out. Send now lifts such a pause, so use it once the cause is gone.
Monitoring delivery
Administration → Email also holds the delivery log: every attempt, its result, and the reason when it failed. Turn to it when you need to know what happened to a message — including the "no transport assigned" case described above. Every attempt is logged, failures included; a message still waiting its turn never appears here — look for it in the Outgoing queue block. The full order of checks is in When mail doesn't arrive.
The log keeps the whole message: the full recipient list, the subject and the body. It answers not only "was it delivered" but "what exactly went out" — and for the same reason it holds customer correspondence and notification text. Bear that in mind when granting access to the administration area.
When mail doesn't arrive
Check in this order — most common cause first:
- Is the transport enabled? Administration → Plugins: a disabled feature carries nothing, and its page isn't in the menu.
- Are the credentials right? On the transport's page press Check connection, then send yourself a test message. The test bypasses purposes — if it arrives, the provider isn't the problem.
- Is the transport assigned to that kind of mail? No password resets — check Administration → Settings; notifications — Notification gateways; customer replies — Service Desk; rule mail — Automation. An unassigned purpose is flagged with a warning in the summary on Administration → Email.
- Is the message still waiting? Look at the outgoing queue: it shows the reason for the delay and the time of the next attempt.
- What does the delivery log say? It records every attempt with the reason it failed — enough to tell whether to fix a setting, wait, or take it up with the provider.
- A cloud instance? Check the platform limits on the transport's page: the daily allowance may be used up.
- Sent but nobody sees it? From there it's the recipient's mail: the spam folder, filters, and the SPF, DKIM and DMARC records of your domain. The log shows a successful send in this case, and rightly so — the product handed the message to the provider.
Where to go next
- Plugins — enabling transports and other features.
- Automation — rules that send mail and handle incoming messages.
- Webhooks — how receiving external events works, which is what mail intake runs on.
- Search & notifications — what the notifications themselves look like.
See also
- Features & settings → Global settings — where the transport for system mail is assigned.
- Agent guide → Configuration — the Service Desk purpose, and threading of customer replies.
- Profile & security → Your password — password reset, which doesn't work without system mail.
- Configuration → Email — why there are no
SMTP_*variables.