E-mail settings
FlowDesk does not produce mail on its own: it sends outgoing mail through your organisation’s
SMTP server and reads incoming mail from your organisation’s mailboxes over IMAP. None of these
settings is an environment variable or a values.yaml field. All of them are entered from the
dashboard and stored in the database. Use the Settings → E-mail settings → E-mail tab.
This needs the mail-settings:view and mail-settings:save permissions in the dashboard; adding
a mailbox additionally needs mail-accounts:mail-account-create:save. A user with view
permission only sees the settings but not the Edit and Send buttons.
Have these ready
Section titled “Have these ready”| Information | Where from |
|---|---|
| SMTP server address and port (587/STARTTLS or 465) | Your mail administrator |
| Sender address and display name | Your organisation’s choice |
| SMTP username and password | Your mail administrator |
| Incoming mailbox address(es) | Your organisation’s choice |
| IMAP server address and port (usually 993) | Your mail administrator |
The SMTP username and the visible sender address do not have to be the same. FlowDesk keeps them in separate fields. If you use a relay without authentication, leave the username empty; when it is empty FlowDesk never attempts to sign in.
Outgoing mail: the SMTP server
Section titled “Outgoing mail: the SMTP server”On the SMTP server settings card press Edit and enter the server address, the port and the Use STARTTLS option. Leave STARTTLS on: turning it off means the session is established unencrypted and your password crosses the network in the clear; turn it off only if your server genuinely expects no encryption. Once saved, the card shows the Configured badge.
Then on the System e-mail identity card enter the sender address, the display name, and the SMTP username and password if there is one. This becomes the sender of mail that belongs to no mailbox (one-time passwords, welcome e-mails, notifications). The password field always appears empty after saving. That is not a bug; it is the sign that the server does not read the password back. Leaving it empty means “keep the current password”, not “delete it”.
After saving, use Send test to send a test message to an address. The most common outcomes:
| Message | Meaning |
|---|---|
| Sent successfully | The server accepted the mail: check the recipient’s inbox and spam folder |
| The server rejected the connection or the sending identity | The username/password or the sender address was rejected by the server |
| Could not reach the e-mail server | No connection at network level: is the address/port right, is egress open |
| The send attempt timed out | Usually a firewall dropping the packet silently |
| E-mail sending is not configured | The SMTP server or the sender identity is missing |
A successful test does not mean the mail was delivered. It only proves the server accepted it.
DNS records for deliverability
Section titled “DNS records for deliverability”Even with correct SMTP settings, receiving servers can reject your mail or file it as spam. Publish three records in your own DNS:
- SPF: states that the SMTP server you use is authorised to send on your behalf. Add to your existing SPF record; a domain can have only one SPF record.
- DKIM: signs outgoing mail; you put the selector and public key your mail server generates into DNS.
- DMARC: states what a recipient should do when SPF/DKIM do not align. Start with
p=none, watch the reports, and tighten once deliverability is stable.
Incoming mail: mailboxes (IMAP)
Section titled “Incoming mail: mailboxes (IMAP)”From the Mailboxes table on the same page, open a record with Add mailbox:
| Field | Description |
|---|---|
| Name | The label shown in the dashboard |
| Mailbox address | The real address, for example support@yourcompany.com |
| IMAP server / Port | Usually 993 |
| Connection security | SSL on connect (993) or STARTTLS (143) |
| Username / Password | The IMAP account for this mailbox |
| Folder | INBOX by default |
| Ingest mode | See below |
| Post-process action | See below |
| Poll interval | Between 10 and 3600 seconds |
Ingest mode is the most critical field: with IMAP selected FlowDesk polls the mailbox
regularly; with Webhook selected the mailbox is never polled and mail is pushed to FlowDesk by
your mail provider (Mailgun, for example) through the
v1/integration/inbound-email/webhook endpoint (see
Webhooks and automation);
with None selected the mailbox is neither polled nor listened to (useful for pausing it).
Post-process action decides what happens to the message on the IMAP server once it has been
turned into a request: Mark as read (the default) sets \Seen, Move to folder moves it to
another folder you name (the target folder name is required with this option), and Do nothing
leaves the message untouched.
If the Pool match column is empty, no pool is configured to accept mail sent to that address. The mail is read but has nowhere to go. Open the pool and set its incoming e-mail address to this mailbox: the field lists the mailboxes defined here, each marked IMAP or webhook, and a pool is bound to a mailbox by that address matching exactly.
A pool’s outgoing e-mail address — what the customer sees a reply come from — offers only mailboxes collected over IMAP, because a reply to any other address is not read back onto the request.
The Test connection button on the form attempts a real IMAP connection; when re-testing a saved mailbox you do not have to type the password again.
| Message | What to do |
|---|---|
| The server rejected the username or password | Check the credentials; make sure IMAP access is enabled on the account |
| Could not establish a secure connection to the server | Does the connection-security choice match the port (993→SSL, 143→STARTTLS) |
| Could not reach the mail server | Wrong address/port, or network egress is closed |
| The specified folder was not found in this mailbox | Check the folder name (there can be case or language differences, such as INBOX versus a localised name) |
| This port is not on the allow list for connection tests | Connection tests allow only 143 and 993 |
Connection tests are limited to 10 attempts per minute; if you hit the limit, wait a short while.
Post-setup checklist
Section titled “Post-setup checklist”- The SMTP and system e-mail identity cards show Configured
- The test send succeeded and the test mail actually reached the inbox (not spam)
- SPF, DKIM and DMARC records are published
- The connection test succeeds for every mailbox
- Every mailbox has the right Ingest mode
- No row in the Pool match column is empty
Common situations
Section titled “Common situations”The test succeeds but mail does not arrive. Almost always DNS: check SPF/DKIM/DMARC first, then the recipient’s spam folder.
The test send works, but replying to a request fails. If the test send from this page succeeds, your SMTP settings are correct and the failure is about that one request, not the server. The usual cause is that the request carries no requester e-mail address: there is no one to send the reply to. FlowDesk reports this as The e-mail could not be sent, it has no recipient address.
Requests opened from an incoming mail always carry the sender’s address. The ones that can be missing it are requests created by hand from the dashboard, or through a request form that has no e-mail field, where the address is optional. To reply anyway, uncheck Send e-mail while processing the request; the address cannot be added to a request after it has been created, so a request that must be answered by mail has to be opened with the address filled in.
Instances on 0.2.1 or earlier report this same case as The configured mail server could not be reached, which reads like a connection problem and is not one. If you see that message while a test send from this page succeeds, this is what it means.
A mailbox used to be read and no longer is. Check the Ingest mode: if it is set to None
the mailbox has been paused deliberately.
I cannot see the settings in the dashboard / there is no Edit button. You do not have the
mail-settings:view or mail-settings:save permission; ask your dashboard administrator.
Passwords are never shown back in the dashboard, in logs or in API responses; who changed a setting and when is written to the audit log.