SMTP
Sends mail through your own SMTP server.
Capability: notifications · Notifications. This is a core capability: the platform asks it questions, so exactly one connected instance is marked Primary and answers. The first instance you enable becomes Primary automatically; a second one never steals the role.
Configure SMTP in Atrium → (admins only)
Setup
Send through any standard SMTP relay (your mail provider, a self-hosted server, or a service like Postmark/SES). You supply the host, port and credentials.
- Get the SMTP endpoint from your provider. Find the SMTP host and port. Use 465 with TLS on (implicit SMTPS) or 587 with TLS off (STARTTLS upgrade).
- Create or copy SMTP credentials. Most providers issue a dedicated SMTP username/password (often an app password or API-key pair). Leave both blank only for an unauthenticated internal relay.
- Pick an authorized From address. The From address must be one your relay is allowed to send as, or messages get rejected or spam-filed.
What you paste back into Atrium
In order, the values the steps above produce:
- Host + port
- Username + password
- From address
How it works
The same send seam as Plunk, backed by nodemailer against any standard relay. Atrium opens an SMTP connection per message, hands over the envelope, and closes it. Your relay decides delivery, retries and reputation; Atrium only reports whether the handoff succeeded.
What Atrium does, and when
| When this happens | Atrium does this |
|---|---|
| Any platform notification (access request, invite, membership change, broadcast) | One SMTP transaction to the configured host and port, authenticated with the stored username and password when both are set. |
| Port 465 with TLS on | Implicit TLS (SMTPS): the socket is encrypted before the SMTP conversation starts. |
| Port 587 with TLS off | STARTTLS upgrade: the connection opens in the clear and is upgraded before credentials are sent. |
Guarantees and limits
- Leaving username and password blank sends unauthenticated, which is only correct for an internal relay that trusts the source IP. Set both for anything reachable from outside.
- Notifications is a core capability, so exactly one connected instance is Primary and sends. SMTP and Plunk can both be connected without duplicating mail.
- The password is encrypted at rest (AES-256-GCM) and never returned to the browser.
What "Test connection" proves
Opens a real connection to the host and port and completes the SMTP handshake (including auth when credentials are set), then closes without sending. A pass proves the relay is reachable and the credentials are accepted, not that it will accept your From address.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Connection times out. | Outbound SMTP is commonly blocked by the hosting provider, or the port is wrong for the TLS mode. | Check that the port matches the mode (465 with TLS on, 587 with TLS off) and that the container can reach the host at all. |
| Handshake succeeds, sends are rejected with a 5xx. | The relay does not permit the From address you configured. | Use a From address the relay is authorised to send as. On managed relays this usually means a verified domain or sender identity. |
| Mail is delivered but lands in spam. | SPF/DKIM/DMARC for the From domain do not cover this relay. | A DNS-side fix on the sending domain, not an Atrium setting. Align the records with your relay's published requirements. |
Configuration fields
| Field | Type | Required | Notes |
|---|---|---|---|
hostHost | text | yes | e.g. smtp.example.com |
portPort | number | yes | e.g. 465 |
secureTLS (implicit, port 465) | boolean | no | On for SMTPS (465). Off uses STARTTLS upgrade (587). |
userUsername | text | no | |
passwordPassword | passwordsecret | no | SMTP auth password. Omit for an open relay. |
fromEmailFrom address | text | yes | e.g. atrium@example.com |
fromNameFrom name | text | no | e.g. Atrium |
Operating notes
- Secret fields are encrypted at rest (AES-256-GCM) and never returned to the client. Editing an instance and leaving a secret field masked keeps the stored value.
- Adding a connector from the marketplace creates a disabled, credential-less instance ("Added, not yet connected"); it does nothing until an admin opens it, pastes credentials, and enables it.
- Use Test connection on the instance page before enabling: it performs a read-only probe with the credentials you entered.
- Connector credentials live in the Atrium database, not in container env vars; changing them here takes effect without a redeploy (within the resolver's 30-second cache).