Email delivery

What this page configures

Email delivery is one setting for the whole installation: the transport DFIRe sends through, the addresses it sends from, and the limits it sends within. It lives at Settings → Email Delivery, and only superusers can open it. Delivery stays off until you select a provider. The test message on the same page confirms the settings work before you rely on them.

Choosing a provider

Six options exist today.

Provider	What it does
Off	The default. DFIRe sends no email, and the test message is unavailable.
SMTP	DFIRe connects to a mail server you name and hands the message over. Any server that speaks SMTP works, your own included.
Amazon SES	DFIRe calls the Amazon SES sending API in a region you choose. Suited to an installation already running on AWS, where the machine's own role can supply the credentials.
Mailgun	DFIRe calls the Mailgun sending API for a domain you have verified with them. Suited to an installation that wants a sending service without an AWS account.
Microsoft 365	DFIRe sends through Microsoft Graph as one mailbox in your Microsoft 365 organization. Suited to an installation whose mail already runs there. DFIRe signs in as a registered application, not with a mailbox password.
Google Workspace	DFIRe sends through the Gmail API as one user in your Google Workspace domain. Suited to an installation whose mail already runs there. A service account acts as that user, so DFIRe never handles a mailbox password.

SMTP is the option for an installation with no route to the internet. Point it at a relay inside your own network, and nothing leaves the perimeter. Amazon SES, Mailgun, Microsoft 365 and Google Workspace all need outbound HTTPS to the provider.

Sender settings

These apply to every message DFIRe sends, whichever provider carries it.

Field	What to enter
From address	The address messages come from. Required once you select a provider. A provider refuses an address it does not consider its own.
From name	The name shown beside the address, such as "DFIRe". Optional.
Reply-to address	Where replies go instead of the from address. Optional, and useful when the from address is a mailbox nobody reads.

Layout

DFIRe assembles every message it sends from three pieces: a header, the notifier's body, and a footer. The header and the footer belong to the installation, so one edit changes every notification. The notifier owns the body, and its author writes it in Markdown.

Write the header and the footer in HTML. Mail clients ignore a stylesheet, so put any styling in style attributes on the elements themselves. DFIRe ships a header with the DFIRe logo and the organization name, and a footer saying the message came from DFIRe. Edit either, clear it to send nothing there, or select Use default header or Use default footer to get the shipped one back.

Each field holds up to 64 KB, and the HTML part of one assembled message up to 512 KB. DFIRe refuses a message over that limit and does not retry it. The delivery record names the limit.

Every message carries an HTML part and a plain text part. A client that renders HTML shows the layout. A client that does not shows the header and the footer with their tags removed. The body reaches it as the Markdown its author wrote. A notifier set to Plain text only sends the text part alone, with no header, footer or logo.

Variables

The header and the footer take the same {{variable}} references a notifier body takes. Two families reach every event, and those are the ones a layout should use. The meta.* family carries the event, the time, the organization name, and the case and installation addresses. The email.* family carries the people the event concerns. A family tied to one kind of event, such as case.*, renders as nothing on an event without a case. The full list is on the Webhooks and Email page.

DFIRe inserts every value as text. A case title containing <script> arrives as those characters and never as markup. The |markdown modifier belongs to a notifier's body and does nothing here.

The logo

The layout reuses the organization logo from Settings → Global Settings. Reference it as an image whose source is cid:logo, and DFIRe attaches the image to the message. The DFIRe logo in the shipped header is cid:dfire. It ships with DFIRe, so it needs no upload and always renders.

<img src="cid:logo" alt="" height="32">

Attaching it is what makes it show. A mail client decides for itself whether to fetch an image from the web, and most refuse until the reader asks. An image that has to appear belongs in the logo rather than at a URL. An installation with no logo attaches nothing, and the reference renders as a broken image the preview shows.

What sanitizing allows

DFIRe cleans the header, the footer and the rendered body before a message goes out. What survives is what a mail client renders.

• Structure and text: paragraphs, line breaks, rules, blockquotes, preformatted text, headings, and the inline tags for bold, italic, underline, strikethrough, code and small print.
• Lists and tables, with their captions, column groups, headers and footers.
• Links to a web address or a mail address. A link to anything else goes.
• Images from a web address, and the organization logo and the DFIRe logo the layout attaches.
• Inline style attributes for colour, fonts, text, spacing, borders and box size. A declaration that fetches something, such as a url() value, goes.

DFIRe removes scripts, style elements, frames, embedded objects, forms and event handler attributes, along with any tag outside the list above. The text inside a removed tag stays, so nothing a reader should see goes with it.

Preview

Preview renders the layout around a sample notification. Both parts of the result are there, the HTML part in a frame and the text part on its own tab. It uses the fields as they stand on screen, so you can read an edit before saving it. The test message on this page goes through the same layout, so you can check a saved one in a real mailbox.

SMTP settings

Temporary SMTP recipient or authentication refusals (4xx responses) use the notifier's configured retries. Permanent recipient or authentication refusals (5xx responses) stop delivery without retrying.

These appear once SMTP is the provider.

Field	What to enter
Host	The name or address of the mail server. Required.
Port	The port the server listens on, 1 to 65535. Required.
Security	How DFIRe protects the connection. See the modes below.
Timeout (seconds)	How long DFIRe waits for the server, 1 to 300. The default is 30.
User name	The account DFIRe signs in as. Leave blank if the server needs no sign-in.
Password	The password for that account. DFIRe stores it encrypted and never shows it again. The field stays blank and marks the stored password as configured. Leave it blank to keep that password, type to replace it, or choose Clear to remove it.

Security modes

Mode	What it does	Usual port
STARTTLS	Opens a plain connection and upgrades it to TLS. The common choice for a submission server.	587
SSL/TLS	Negotiates TLS from the first byte.	465
None	No transport encryption. Use it only on a network you control, such as a relay on the same segment.	25

Amazon SES settings

These appear once Amazon SES is the provider.

Field	What to enter
Region	The AWS region DFIRe sends through, such as eu-north-1. Required. SES accepts a message only from an identity you verified in that region.
Configuration set	The name of an SES configuration set, applied to every message DFIRe sends. Optional. Use it when you already collect delivery events in SES.
Access key ID	The first half of an IAM access key. Leave it blank, together with the secret, to use the credentials of the machine DFIRe runs on.
Secret access key	The second half of that key. DFIRe stores it encrypted and never shows it again. Leave it blank to keep the stored key, type to replace it, or choose Clear to remove it.

What to set up in AWS

Do three things in the AWS console before you select Amazon SES.

1. Verify the identity the from address belongs to, either the address itself or its whole domain, in the region you plan to use.
2. Move the account out of the SES sandbox if you send to addresses you have not verified.
3. Allow the ses:SendEmail action on that identity. Grant it to an IAM user and give DFIRe that user's access key. Or grant it to the role attached to the machine DFIRe runs on, and leave both key fields blank.

Mailgun settings

These appear once Mailgun is the provider.

Field	What to enter
Sending domain	The domain you added to Mailgun, such as mg.example.com. Required. The from address should belong to it.
API key	A Mailgun sending API key. Required. DFIRe stores it encrypted and never shows it again. Leave it blank to keep the stored key, type to replace it, or choose Clear to remove it.
API endpoint	Which Mailgun region answers for the domain. The default is the US endpoint. Use https://api.eu.mailgun.net/v3 for a domain created in the EU region.

What to set up in Mailgun

Do two things in the Mailgun dashboard before you select Mailgun.

1. Add your sending domain and publish the DNS records Mailgun gives you, until the domain shows as verified.
2. Create a sending API key in the same region as the domain. Mailgun refuses a key from the other region, so set the API endpoint to match.

Microsoft 365 settings

These appear once Microsoft 365 is the provider. All four are required.

Field	What to enter
Directory (tenant) ID	The Microsoft Entra ID directory the application belongs to.
Application (client) ID	The registered application DFIRe signs in as.
Client secret	The secret that application signs in with. DFIRe stores it encrypted and never shows it again. Leave it blank to keep the stored secret, type to replace it, or choose Clear to remove it.
Sender mailbox	The mailbox DFIRe sends from, such as [email protected]. The from address must be this mailbox, or an address it may send as.

What to set up in Microsoft 365

Do this in the Microsoft Entra admin center before you select Microsoft 365. Step four is optional, and worth doing.

1. Register an application in Entra ID. Its directory and application identifiers are the first two fields above.
2. Add the Microsoft Graph application permission Mail.Send, then grant admin consent. Without consent the application receives no token, and the test message reports the refusal.
3. Create a client secret and note the date it expires. Sending stops on that date, so put the renewal in a calendar.
4. Limit the application to the sending mailbox with an Exchange Online application access policy. Until you do, Mail.Send covers every mailbox in the organization. The PowerShell cmdlet is New-ApplicationAccessPolicy.

DFIRe reaches login.microsoftonline.com for the token and graph.microsoft.com for the send. Microsoft fixes both addresses, so this provider is not for an installation without a route to the internet.

Google Workspace settings

These appear once Google Workspace is the provider. Both are required.

Field	What to enter
Sender mailbox	The Workspace user DFIRe sends as, such as [email protected]. The from address must be this user, or an address they may send as.
Service account key	The JSON key file for the service account, pasted in full. DFIRe stores it encrypted and never shows it again. Leave it blank to keep the stored key, paste a new one to replace it, or choose Clear to remove it.

What to set up in Google

Do this before you select Google Workspace. The first three steps are in the Google Cloud console, the fourth in the Google Workspace admin console.

1. Create a Google Cloud project, or pick one you already have.
2. Enable the Gmail API for that project.
3. Create a service account and download a JSON key for it. Note its client ID, which the next step needs.
4. Grant domain-wide delegation to that client ID for the scope https://www.googleapis.com/auth/gmail.send. Until you do, Google refuses every send, and the test message reports the refusal.

The sender mailbox must belong to the domain where you granted the delegation. The scope covers sending only, so the service account cannot read any mailbox.

DFIRe reaches oauth2.googleapis.com for the token and gmail.googleapis.com for the send. Google fixes both addresses, so this provider is not for an installation without a route to the internet.

Recipient domains and the per-minute cap

Two limits apply to the email notifications DFIRe sends.

Recipient domains names the domains DFIRe may send to beyond its own users. DFIRe accepts the address of an active user account without listing its domain, so a blank list keeps mail inside the user base. A service account is not written to, and neither is the placeholder address an unlinked SSO account carries. Write each domain in lower case, separated by commas, for example example.com, example.org. DFIRe refuses every other address, which is what keeps a notification from leaving for somewhere nobody chose. A blank list is the strictest setting, not the absence of one. The list applies to what notifiers send: a test message from this page goes to the address you type, listed domain or not.

Messages per minute caps how much DFIRe sends in a minute, from 1 to 10000. The default is 60, and every notifier counts against the same cap. A message over the cap waits a minute and tries again, so a burst of events arrives late rather than not at all. After ten minutes of waiting it fails, and the delivery history names the cap as the reason. A test message never counts against the cap. Keep the cap under the rate your mail server accepts, so a busy period does not get the installation throttled or blocked.

Sending a test message

The test section sends one message through the provider you configured and reports what happened. The address defaults to your own and you can send to any other.

1. Save the settings first

   The test uses the stored configuration, not what is on screen, so save before you test.

2. Select Send test

   The message is a sample notification inside your layout, so a real mailbox shows what a recipient gets. The button is unavailable while the provider is Off.

3. Read the outcome

   Success means the provider accepted the message. A refusal names the reason the provider gave: a rejected credential, a refused recipient, an unverified sender, or a provider DFIRe could not reach. The time and outcome of the last test stay on the page.

An accepted message is not a delivered one. If the test reports success and nothing arrives, something further along dropped or filtered it. Your mail server's own logs are where that shows.

For Microsoft 365, open the Exchange admin center and select Mail flow → Message trace. Search by sender, recipient and time, then open the result for the delivery events and any rejection reason.

Email links need the full address of the installation. Save it under Settings → Single Sign-On → Application Base URL, even if you do not use single sign-on. Background notifications cannot detect the address from a browser request. The test message uses an example case link. Trigger a notifier for a real case to check its destination.

What is recorded

Both actions on this page reach the audit log.

Saving the settings records which of them changed, with the value before and after. A changed password leaves a marker in place of both values.

Sending a test records the address it went to and the outcome, including the reason a refused message gave. DFIRe records a failed test as readily as a successful one, so a configuration that never worked leaves the same trail as one that did.