Email and attachments
Fixes for email that isn't sent, emailed requests that aren't filed, uploads refused for malware, scanning or storage quota, and files that can't be downloaded.
- Where
- Admin → Settings → Organization settings → Channels · Admin → Settings → Integrations · /api/health · /api/health/ready?require=scanner
- Permission
- MANAGE_SETTINGS (email channel) · MANAGE_INTEGRATIONS (rejection notices) · admin of the host, cluster or server (self-hosted settings)
- Updated
- October 2026
Before you start
Each heading is a symptom. Under it: the likely cause, then what to check.
Upload and download errors return JSON with an error message and a code. The table at the end lists each code.
Self-hosted: GET /api/health with Authorization: Bearer <METRICS_TOKEN> reports the smtp, email_sender, app_url and scanner checks, each with a message.
Self-hosted: the app log is JSON, one line per event. Mail and upload problems carry the sources email-config, email.delivery, email.inbound and attachments.scan.
Problems and fixes
- 01
No email is sent at all
On a self-hosted install, email is off when
EMAIL_DELIVERY_MODE=off, or when it isauto(the bundles' default) andSMTP_HOSTis blank. Every send is then skipped on purpose, without an error, and notifications are in-app only.- The sign-in page shows “Forgot it? Ask an administrator.” in place of Forgot password?
- Password reset by email answers 409
EMAIL_OFF - Launch readiness on the setup page lists Outbound email delivery as turned off
- Without email, people sign in with passwords an admin sets in Admin → Users, or through single sign-on (SSO)
- To turn email on, fill in the values below and restart. With
auto, settingSMTP_HOSTis what turns it on
Settings file (.env or eventier.env)bash EMAIL_DELIVERY_MODE=auto SMTP_HOST=smtp.yourcompany.com SMTP_PORT=587 SMTP_USER= SMTP_PASS= SMTP_FROM="EvenTier <no-reply@yourcompany.com>" - 02
Email fails because a setting is missing
In production, every send needs
SMTP_HOST(your outgoing mail server, or SMTP relay) andSMTP_FROM. The app starts without them, but each send fails and names the missing setting.- At startup the app log has an
email-configwarning naming the setting SMTP_FROMmust look likeEvenTier <no-reply@yourcompany.com>; quote it in the settings file- A sender on a reserved domain such as
.localis rejected by mailbox providers, and theemail_senderhealth check fails - Server install:
./install.sh --checklists a blankSMTP_HOSTorSMTP_FROM
Find the warningbash # Docker Compose docker compose logs app | grep email-config # Server journalctl -u eventier | grep email-config - At startup the app log has an
- 03
The mail server refuses the connection or the login
EvenTier reaches your relay but can't connect or sign in to it. The
smtphealth check shows the relay's reply.- Port 587 uses STARTTLS; port 465 uses TLS from the start
- Check
SMTP_USERandSMTP_PASS, and that the relay may send for theSMTP_FROMdomain - Docker Compose and Kubernetes: the test script below connects and signs in without sending anything
- Add
--to you@example.comin place of--verify-onlyto send one real test message - A failed send is retried in the background for about a day, so mail queued during an outage still goes out once the relay is back
Test the relay from inside the app containerbash # Docker Compose docker compose exec app node_modules/.bin/tsx scripts/email-test-send.ts --verify-only # Kubernetes kubectl exec deployment/eventier -c web -- node_modules/.bin/tsx scripts/email-test-send.ts --verify-only - 04
One person never gets email
Their address is probably on the suppression list after a hard bounce or a spam complaint. EvenTier sends nothing to a suppressed address, invites and password resets included.
- An address is suppressed when the receiving server permanently refuses the mailbox, or Amazon SES reports a permanent bounce or a complaint
- When an admin adds a user whose address is suppressed, the user is created and the admin is told the invite was not sent
- Deactivated users get no notification emails
- Self-hosted on Docker Compose or Kubernetes: check the address with the script below
- Remove an address only after its owner confirms the mailbox works
Check and lift a suppression (Docker Compose)bash docker compose exec app node_modules/.bin/tsx scripts/email-suppression.ts show someone@example.com docker compose exec app node_modules/.bin/tsx scripts/email-suppression.ts remove someone@example.com - 05
Links in email open the wrong address
Links are built from
NEXT_PUBLIC_APP_URL, or fromNEXTAUTH_URLwhen that is unset.- Server: set
NEXT_PUBLIC_APP_URLto the https address people open - Docker Compose builds it from
EVENTIER_DOMAIN; Kubernetes fromapp.url - The
app_urlhealth check shows the address in use - A startup warning says when
NEXT_PUBLIC_APP_URLis unset
- Server: set
- 06
An emailed request never appears
EvenTier files mail only from active members of the workspace, and only when the mail passes DMARC, the check that proves mail really comes from the sender's domain.
- People with
MANAGE_INTEGRATIONSget “Inbound message rejected” with the reason, at most once a day per workspace - Sender not a member: invite them, or have them use the portal
- Sender could not be authenticated: a DMARC fail is always refused, and EvenTier Cloud accepts only a DMARC pass
- The sender's domain needs a DMARC record;
p=noneis enough - Email channel enabled must be on; mail sent while it is off is not filed
- Email needs an active request type to be filed under
- Out-of-office and other automatic replies are ignored on purpose, and a message that arrives twice is filed once
- Admin → Settings → Organization settings → Channels
- Email channel enabled
- People with
- 07
Self-hosted: mail from your relay is not accepted
On a self-hosted install, requests by email stay off until you set
INBOUND_EMAIL_ENABLED=true. Your mail relay then posts each message as JSON to/api/email/inbound.- While it is off, the endpoint answers 404
- Each post needs the
x-eventier-inbound-secretheader set toINBOUND_EMAIL_SECRET - A missing or wrong secret gets 401 “Inbound email secret is invalid.”
- In production, an unset
INBOUND_EMAIL_SECRETrefuses all inbound mail - A message over 10 MB gets 413
- Enter the address your relay receives on in the Channels tab
Settings filebash INBOUND_EMAIL_ENABLED=true INBOUND_EMAIL_SECRET=<openssl rand -hex 32> - 08
Attachments are missing from an emailed request
An email can carry up to 10 files of the allowed types. Files beyond the limits are left out, and the request is still filed.
- Allowed types: PDF, PNG, JPG, TXT, CSV, DOCX and XLSX
- EvenTier Cloud: 10 MB per file and 15 MB in all
- Self-hosted relay: the whole message must be under 10 MB, which leaves about 7 MB for files
- People with
MANAGE_INTEGRATIONSget “Inbound email attachments skipped”, naming the files - A file that contains malware is refused
- While the scanner is unavailable, the delivery is retried, so the file is not lost
- 09
Upload fails: “malware was detected”
The scanner (ClamAV) flagged the file. The upload answers 422
MALWARE_DETECTEDand nothing from it is stored.- The message names the file: “… was blocked because malware was detected in it. No files were stored.”
- No file from that upload was stored, so send the others again without it
- Each detection is recorded in Admin → Audit logs → Security events as
attachment.malware_detected, with the signature and the file's SHA-256 hash
- 10
Upload fails: “Attachment scanning is temporarily unavailable”
Scanning is set up, but the scanner gave no verdict: clamd is down, still loading its signatures, timed out or replied with an error. The upload answers 503
SCANNER_UNAVAILABLE.- Try again in a few minutes
- clamd answers only after its first signature download, a few minutes after install
- Self-hosted:
/api/health/ready?require=scanneranswers 503 until clamd answers - Give clamd 3 to 4 GB of memory; it holds the signatures in memory
- Air-gapped: clamd refuses to start without signature files, so copy them in
- Or run without scanning on a self-hosted install:
ATTACHMENT_MALWARE_SCANNER=off
Check clamdbash # Docker Compose docker compose ps clamav docker compose logs --tail 50 clamav # Any path: 200 once clamd answers curl -sS "https://<your domain>/api/health/ready?require=scanner" - 11
Upload fails: “Attachment scanning is not configured”
Scanning is required, but no usable scanner is set. The upload answers 503
SCANNER_NOT_CONFIGURED, and every upload fails until it is fixed.ATTACHMENT_MALWARE_SCANNERmust beclamav, oroffon a self-hosted install- With
clamav,CLAMAV_HOSTandCLAMAV_PORTmust point at clamd - Any other scanner name refuses every upload
offis honored only on self-hosted installs- Kubernetes:
clamav.enabled: falsealone turns scanning off on a self-hosted install - The
scannercheck of/api/health, and anattachment-configline in the startup log, name the problem
Settings file (server install with your own clamd)bash ATTACHMENT_MALWARE_SCANNER=clamav CLAMAV_HOST=127.0.0.1 CLAMAV_PORT=3310 - 12
Upload fails: “reached its attachment storage quota”
The workspace's stored attachments add up to its quota, 5 GiB by default. The upload answers 413
ATTACHMENT_QUOTA_EXCEEDED.- The quota is the total size of every attachment stored in the workspace
- Profile photos and import CSV files don't count toward it, but a workspace over the quota can't upload them either
- Self-hosted: raise it with
ATTACHMENT_ORG_QUOTA_BYTES, in bytes, then restart
Settings file: a 10 GiB quotabash ATTACHMENT_ORG_QUOTA_BYTES=10737418240 - 13
Upload refused for its size or type
Each file can be up to 10 MB, and only some types are accepted. The file's contents must also match its extension.
- Over 10 MB: 413 “A file exceeded the per-file upload limit.”
- Wrong type: 400 “That file type is not allowed. Upload PDF, image, text, CSV, DOCX, or XLSX files only.”
- Accepted: .pdf, .png, .jpg, .jpeg, .txt, .csv, .docx and .xlsx
- Contents don't match the extension: 400 “The file contents do not match its type.”
- Knowledge base images: PNG, JPEG, GIF or WebP, up to 10 MB
- 14
Download fails: “stored without a malware scan”
The file was stored without a scan, and scanning is now required. The download answers 403
ATTACHMENT_NOT_SCANNED.- Scanning is required in any production runtime, with S3 attachment storage, or with
ATTACHMENT_SCAN_REQUIRED=true - Files a self-hosted install stored while
ATTACHMENT_MALWARE_SCANNER=offstay downloadable after scanning is turned back on - Ask for the file to be uploaded again, so it is scanned
- Scanning is required in any production runtime, with S3 attachment storage, or with
Error codes
Codes returned by uploads, downloads and password reset, with the HTTP status.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| MALWARE_DETECTED | 422 | The scanner found malware; nothing was stored | Upload the other files again without it |
| SCANNER_UNAVAILABLE | 503 | clamd is down, loading signatures, timed out or replied with an error | Wait, then check clamd |
| SCANNER_NOT_CONFIGURED | 503 | Scanning is required but no usable scanner is set | Set ATTACHMENT_MALWARE_SCANNER and CLAMAV_HOST / CLAMAV_PORT |
| ATTACHMENT_QUOTA_EXCEEDED | 413 | The workspace is at its attachment storage quota | Self-hosted: raise ATTACHMENT_ORG_QUOTA_BYTES |
| ATTACHMENT_NOT_SCANNED | 403 | The file was stored without a scan, and scanning is now required | Upload the file again |
| EMAIL_OFF | 409 | Password reset by email while email is turned off | An admin sets a new password |
Good to know
- Running without email? Leave
EMAIL_DELIVERY_MODE=autowithSMTP_HOSTblank, or set it tooff: health checks and launch readiness then report it as a choice. Onlysmtptreats a missing relay as a fault. - After a relay or scanner outage, nothing needs resending: queued email is retried for about a day, and inbound email retries its attachments.
- Test requests by email from a member's own mailbox, on a domain that publishes DMARC.