Email & Newsletters

Tracearr sends two kinds of email. Alerts are what an automation routes to an email destination, the same way it routes to Discord or ntfy. Newsletters are a digest of what was added to a server over a window, sent to that server’s members on a schedule, with an unsubscribe link in every message.

Both go through one SMTP destination, one rendering package and one branding block. Nothing is sent through a provider’s HTTP API.

The email destination

Alerts and newsletters both need an email destination under Settings → Notifications → Destinations. Only the owner can add one. What every destination has in common is on the Notification destinations page. The rest of this section is the part specific to email.

Add the destination

Click Add destination and pick Email.

Pick a provider

Provider fills the SMTP host, port and security for the seven providers listed below. Custom leaves all three to you.

Fill the account

What goes in Username and Password differs by provider, and the description under each box names it for the provider you picked. From address is what recipients see, and it has to be an address the provider lets you send as.

Test it

Test opens the connection and checks the credentials first, then sends a message with the subject Test email from Tracearr (<destination name>). It goes to Alert recipients, or to the From address when that list is empty.

Provider presets

Provider	SMTP host	Port	Security
Postmark	`smtp.postmarkapp.com`	587	STARTTLS
Resend	`smtp.resend.com`	465	TLS
Amazon SES	`email-smtp.us-east-1.amazonaws.com`	587	STARTTLS
Mailgun	`smtp.mailgun.org`	587	STARTTLS
SendGrid	`smtp.sendgrid.net`	587	STARTTLS
Brevo	`smtp-relay.brevo.com`	587	STARTTLS
Gmail	`smtp.gmail.com`	587	STARTTLS

Picking a provider writes those three values and nothing else, and you can edit any of them afterwards. Amazon SES and Mailgun EU need the region edited into the host.

The fields

Field	Required	Default	Notes
Provider	Yes	`Custom`	Fills the three fields below it from the table above
SMTP host	Yes	none	A hostname or IP address, with no scheme, port or path
Port	Yes	`587`	A whole number from 1 to 65535
Security	Yes	`STARTTLS`	STARTTLS (usually port 587), TLS (usually port 465), or None (plain text, port 25)
Username	No	blank	Leave blank when the server needs no login
Password	No	blank	Stored encrypted, and never read back into the form
Messages per second	Yes	`2`	A whole number from 1 to 50
Message stream	No	blank	Postmark only, up to 64 characters, letters, digits and hyphens
From name	No	`Tracearr`	The display name on the From header
From address	Yes	none	The address recipients see and reply to unless Reply-to is set
Reply-to	No	blank	One address
Alert recipients	No	blank	Comma-separated addresses that alerts go to; newsletters ignore this list

Username and Password are optional, so a relay that wants no login works with both left blank.

Username and password by provider

Each provider names these two differently, and swapping them fails the test with SMTP authentication failed. Once you pick a provider the dialog shows the matching line under each box.

Provider	Username	Password
Postmark	Your Server API token.	The same Server API token, or a stream token’s secret.
Resend	The word resend, exactly.	Your Resend API key. The sender domain must be verified in Resend first.
Amazon SES	The SMTP user name from the SES console, not an IAM access key. Put your region in the host.	The SMTP password from the SES console. Sandbox accounts send 200 messages a day to verified addresses only.
Mailgun	`postmaster@yourdomain`, not your Mailgun login.	The SMTP password from that domain’s settings. A sandbox domain only reaches its authorized recipients.
SendGrid	The word apikey, exactly.	Your SendGrid API key.
Brevo	Your Brevo login email.	An SMTP key from SMTP & API > SMTP, not the API key.
Gmail	Your full Gmail address. Gmail sends from this address whatever the sender address says, and personal accounts stop near 500 recipients a day.	An app password from Google Account > Security > 2-Step Verification > App passwords. Your account password is rejected.

Message stream

Postmark separates transactional and broadcast mail into streams. Put a stream ID in Message stream and Tracearr adds an X-PM-Message-Stream header carrying it to every message sent through this destination. Leave it blank on every other provider; nothing else reads the header.

Rate limit

Messages per second defaults to 2 and accepts 1 to 50. The limit is per Tracearr instance, so two instances behind one Redis send at twice the rate you set here. Stay under whatever your provider allows.

Host validation

SMTP host takes a bare hostname or IP address. Saving with a value that carries a scheme, a port or a path is refused, before anything tries to connect:


host: host must be a hostname or IP address without a scheme, port or path

Link-local addresses are refused as well, both 169.254.0.0/16 and fe80::/10. Private, loopback and CGNAT addresses are allowed, so a relay running on the same box or elsewhere on your LAN works.

Connection behaviour

Tracearr holds one pooled connection set per destination, capped at 2 connections carrying at most 100 messages each. Changing any connection field closes the pool and opens a new one.

Timeout	Value
Connection	30 seconds
Greeting	30 seconds
Socket	120 seconds

Errors from the mail server

Three connection failures are rewritten into text you can act on. Everything else the mail server says is passed through as it arrived.


SMTP authentication failed for <username> at <host>

The server took the connection and rejected the credentials. With Username blank the message reads anonymous, which means the server wanted a login you did not give it.


Could not connect to <host>:<port>

Nothing answered. The connection was refused, it timed out, or the hostname did not resolve.


TLS failed for <host>:<port>; check the security setting

The TLS handshake failed, usually because Security does not match the port. Port 465 wants TLS; 587 wants STARTTLS.

One more comes from Tracearr rather than from the mail server:


No alert recipients on this destination. Add one under Settings, Destinations.

An automation sent an alert to a destination whose Alert recipients list is empty. Newsletters do not hit this, because they address their own recipients.

Alerts over email

An automation’s Send Notification action reaches an email destination the same way it reaches any other. The alert goes to the addresses in Alert recipients, and to nothing else. A destination can also be given every violation on its own with the Receive violations switch, which stays disabled until that list holds an address.

Each alert renders as one card: the event title, a severity label reading Info, Warning or High, the message, and the time in UTC. A violation adds the user, the rule, the severity, and the server when the violation names one. Something added to or upgraded in a library adds its poster, the resolution, dynamic range and codec lines, and links out to the item. When an external URL is set under Settings → Access → Remote access, the mail ends with an Open Tracearr link.

The From header carries From name, or Tracearr when you left it blank, and the display name inside the message is the server the event is about.

SPF, DKIM and DMARC

Whether a message lands in the inbox is decided by the receiving provider, and the three DNS records below are what it checks. They live on the domain of the From address, in your DNS host, not in Tracearr.

SPF lists which servers may send for the domain. Your provider gives you the record to add; it looks like v=spf1 include:spf.example-provider.com ~all.
DKIM signs each message with a key the provider holds. The provider gives you one or more CNAME or TXT records to add, and signing starts once they resolve.
DMARC tells receivers what to do when SPF or DKIM fail. Start with v=DMARC1; p=none; rua=mailto:you@yourdomain on _dmarc.yourdomain and tighten to quarantine once reports look clean.

The newsletter editor’s Readiness list flags the one mismatch it can see from Tracearr: “The from address and the SMTP username sit on different domains; some providers refuse that.”

Branding

Settings → Notifications → Email holds the block every email uses, alerts and newsletters alike.

Setting	Default	Notes
Logo	`Tracearr`	Tracearr’s own mark, no logo, or an image at an http or https URL of up to 500 characters
Accent color	`#0ea0b3`	A six-digit hex color
Footer text	blank	One line under every email, up to 500 characters
Postal address	blank	Up to 500 characters; some jurisdictions expect one on bulk mail
Offer unsubscribe by email too	off	Adds a mailto form to the `List-Unsubscribe` header

The mailto form points at the destination’s Reply-to address, so someone has to read that mailbox and act on what arrives. The link in the message footer works either way.

Tracearr’s own logo travels as an attachment. A logo you point at by URL is fetched by the recipient’s mail client instead.

Newsletters

Newsletter scheduling, windows, sections and send history are being documented on their own page at /configuration/email/newsletters. Until it is published, the newsletter editor under Settings → Notifications → Newsletters carries the same information in its field descriptions and its Readiness list.

Recipients and unsubscribes

Who receives a newsletter, how members get a contact email, and the suppression list are being documented at /configuration/email/recipients. Until it is published, the recipients panel in the newsletter editor and the Suppressed addresses list under Settings → Notifications → Email are where those are managed.