Plunk
Sends approval and access mail to your people.
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.
Vendor site · Connector implementation · Vendor docs
Configure Plunk in Atrium → (admins only)
Setup
Atrium sends transactional email (access approvals, notifications) through your Plunk project. Read the secret key from Plunk and verify the domain you send from.
- Open (or create) a Plunk project. Sign in to Plunk and select the project this Atrium instance should send from. Open the console page ↗
- Copy the secret API key. Project → Settings → API keys. Copy the SECRET key (starts with sk_), not the public one.
- Verify your sending domain. Settings → Verified domains. The From address you set below must be on a domain that shows as verified, or Plunk rejects the send.
What you paste back into Atrium
In order, the values the steps above produce:
- Secret API key (sk_…)
- From address on the verified domain
How it works
Every mail the platform sends goes through one seam, resolveEmailProvider(), and this connector is one possible answer to it. Atrium calls Plunk's transactional send API server-side, one HTTP request per message, and never reads anything back. Plunk holds no Atrium state: it is a delivery pipe, not a system of record.
What Atrium does, and when
| When this happens | Atrium does this |
|---|---|
| An access request is raised, approved or denied | One send to the requester (and the approver on a raise) with the rendered HTML body, From set to the configured verified address. |
| A person is invited, or their group membership changes | One send per affected person. The gating and the audit-log lifecycle live in Atrium, not in Plunk, so a disabled connector suppresses delivery without losing the record that the event happened. |
| An admin sends a broadcast notification | One send per recipient, subject to the broadcast rules in lib/email/send.ts. There is no batch endpoint in play; a large group is a large number of individual sends. |
Guarantees and limits
- Notifications is a core capability, so exactly one connected instance is Primary and sends. Connecting SMTP alongside Plunk does not duplicate mail, and it does not silently take over either: primacy is a flag an operator sets, never inferred from which row was edited last.
- Nothing is sent when the capability is unconfigured or the row is incomplete. The send returns a readable "email not configured" error instead of throwing, so the surrounding action still completes.
- The API key is write-only from the client's point of view: it is encrypted at rest (AES-256-GCM) and never returned to the browser, so an admin can see that a key is set but not read it back.
What "Test connection" proves
Probes Plunk's send endpoint with the key and an intentionally empty payload. A 401 or 403 means the key is bad; a 5xx is treated as inconclusive rather than a failure, because the server erred before deciding auth. A pass proves the key authenticates, not that your From domain is verified.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Test connection passes, but no mail arrives. | The From address is not on a domain verified in the Plunk project. Plunk accepts the key and rejects the send. | Plunk → Settings → Verified domains. Either verify the domain or change the From address to one already verified. |
| Mail stopped after another email connector was added. | The new instance was made Primary. Only the Primary sends. | On the connector card, set Plunk back to Primary. Both stay connected either way. |
| Sends fail with an auth error after a key rotation in Plunk. | The stored key is the old one. Rotating in Plunk does not notify Atrium. | Paste the new secret key here. It takes effect within the resolver's 30-second cache, with no redeploy. |
Configuration fields
| Field | Type | Required | Notes |
|---|---|---|---|
apiKeyAPI key | passwordsecret | yes | Plunk project secret key (sk_…). Maps to PLUNK_SECRET_KEY. e.g. sk_… |
fromEmailFrom address | text | yes | Must be on a domain verified in the Plunk project. e.g. atrium@ommax-intelligence.de |
fromNameFrom name | text | no | e.g. Atrium |
baseUrlAPI base URL | text | no | Override for self-hosted Plunk. Defaults to the cloud endpoint. e.g. https://next-api.useplunk.com |
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).