Set up email senders

Who this is for: admins who want workflow email to come from their company’s own address, and the person who manages the company’s DNS and mail.

Before you start: you need the Manage connections permission (manage_connections), and you must be signed in as a person: AI assistants and API tokens cannot set up senders. You also need either SMTP relay details or admin access to your Microsoft 365 tenant, and access to your domain’s DNS.

A sender is the way Liitora sends the email that workflows write with the email.send action. With your own sender, reports come from an address such as reports@yourcompany.com and go out through your own mail system.

In Monitor, select Alerts, then Senders. See the Email senders page. Everything also works through the REST API, at /api/v1/email-senders. Creating, changing, testing and deleting senders needs a signed-in person, so an API token or an AI assistant cannot do it for you.

Which sender is used

For every email a workflow sends, Liitora picks:

1. your company’s default sender, else your first verified sender;
2. that sender must be verified. If it is not, the step fails with email_sender_unverified. Liitora never falls back to another domain once your company has senders;
3. if your company has no senders at all, the Liitora default sender. The email then comes from Liitora’s own address.

If no sender can be used, the step fails with email_not_configured.

Kinds of senders

Kind	How it sends	Credentials
SMTP relay (smtp)	Through your mail server or relay service, always encrypted	A Username and password secret (optional, if the relay needs sign-in)
Microsoft 365 (m365_graph)	Through Microsoft Graph, as a mailbox in your tenant	An OAuth client secret with the app’s client ID and client secret
Liitora default (platform_default)	From Liitora’s own address	None

A sender never holds a password or key itself. It names a secret. If the secret does not exist yet, Liitora creates a request for it with a fill link, so a person enters the value.

Set up an SMTP relay sender

Settings for an SMTP sender:

Setting	Meaning
host	The relay’s host name, for example smtp.example.com
port	The port. Default 587
security	starttls (default, the connection must upgrade to TLS) or tls (TLS from the start, usually port 465). Plain text is not allowed
spf_include	Optional. The SPF include your relay provider asks for, so the DNS check can look for it
dkim_selectors	Optional. Up to 5 DKIM selector names your relay signs with

1. Create a Username and password secret for the relay, or let the request create one.
2. Create the sender with POST /api/v1/email-senders, for example:

{
  "name": "company-relay",
  "kind": "smtp",
  "from_addresses": ["reports@yourcompany.com"],
  "display_name": "Your Company reports",
  "config": { "host": "smtp.example.com", "port": 587, "security": "starttls" },
  "secret_ref": "smtp_relay_login",
  "make_default": true
}

3. If the answer has a secret_fill_url, open it and add the username and password.
4. Verify the sender.

Set up a Microsoft 365 sender

Liitora sends through Microsoft Graph as one mailbox, with an app registration in your Microsoft Entra ID.

1. In the Microsoft Entra admin center, register an app for Liitora.
2. Give it the Microsoft Graph application permission Mail.Send, and grant admin consent.
3. Create a client secret for the app. Note the client ID and the secret value.
4. We recommend limiting the app to the mailboxes it should send from, with an Exchange Online application access policy. Without it, Mail.Send allows sending as any mailbox in your tenant.
5. Create an OAuth client secret in Liitora with the client ID and client secret, or let the request create one.
6. Create the sender:

{
  "name": "m365",
  "kind": "m365_graph",
  "from_addresses": ["reports@yourcompany.com"],
  "config": { "azure_tenant": "yourcompany.onmicrosoft.com", "mailbox": "reports@yourcompany.com" },
  "secret_ref": "m365_mail_app",
  "make_default": true
}

azure_tenant is your Microsoft Entra tenant ID (a GUID like 00000000-0000-0000-0000-000000000000) or one of your tenant’s domain names, like yourcompany.onmicrosoft.com. A short name without a dot, such as yourcompany, is not accepted. If a sender you saved earlier has a tenant value like that, it still sends, but its card shows a warning and you can’t save changes to it until you fix the tenant. mailbox is the mailbox Liitora sends as. To send from other addresses too (send as), list them in from_addresses and give the mailbox the send-as right in Exchange. Attachments can be at most 3 MB per message with Microsoft 365.

7. Verify the sender.

Verify the sender

A new sender is pending. It becomes verified after a test email gets through.

1. Select Send a test email on the sender, or use POST /api/v1/email-senders/{id}/test. It goes to you, the person asking.
2. Check that the email arrived.
3. Check the sender’s status. It is verified, or error with a status_message that says what went wrong.

Every change to the addresses, settings or secret makes the sender pending again, so test again after a change. If a real send later fails with a sign-in or setup error, the sender changes to error and workflows stop sending through it until you fix it and test again.

To make another sender the default, select Make default, or use POST /api/v1/email-senders/{id}/default.

Set up SPF, DKIM and DMARC

These DNS records tell other mail servers that your sender may send for your domain. Without them, reports often land in spam.

Liitora checks them for you: select Check DNS records on the sender, or use GET /api/v1/email-senders/{id}/dns. For each sender domain the answer lists every check as pass, warn or fail, the records found, what was expected and what to do.

Sender addresses must be on a public domain. Liitora refuses addresses on local or internal domains, such as reports@mail.internal or reports@svc.cluster.local, and never looks them up in DNS.

SPF

One TXT record at your domain that lists who may send for it. There must be exactly one v=spf1 record.

For Microsoft 365:

yourcompany.com.  TXT  "v=spf1 include:spf.protection.outlook.com -all"

For an SMTP relay, use the include your provider gives you and set it as spf_include on the sender. If you already have an SPF record, add the include to it instead of creating a second record.

The check fails on +all (anyone may send) and warns on ?all.

DKIM

Your mail system signs each email. The public key is published in DNS at <selector>._domainkey.<your domain>, as a CNAME or a v=DKIM1 TXT record.

For Microsoft 365, turn on DKIM for your domain in the Microsoft Defender portal. It gives you two CNAME records like these, with your own values:

selector1._domainkey.yourcompany.com.  CNAME  selector1-yourcompany-com._domainkey.yourcompany.onmicrosoft.com.
selector2._domainkey.yourcompany.com.  CNAME  selector2-yourcompany-com._domainkey.yourcompany.onmicrosoft.com.

Liitora looks for selector1 and selector2 for Microsoft 365 senders. For an SMTP relay, set dkim_selectors on the sender to the selectors your provider uses.

DMARC

One TXT record at _dmarc.<your domain> that says what receivers do with email that fails SPF and DKIM:

_dmarc.yourcompany.com.  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@yourcompany.com"

p=quarantine and p=reject pass the check. p=none only warns, because receivers then do nothing with failing email. Many companies start with p=none, read the reports for a few weeks, then move to quarantine.

DNS changes can take a while to show up. If the check says it could not look up the records, try again later.

Next steps

• Set up alerts
• Built-in action: email.send
• Your first scheduled report