Skip to content

Documentation

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

  1. 01

    No email is sent at all

    On a self-hosted install, email is off when EMAIL_DELIVERY_MODE=off, or when it is auto (the bundles' default) and SMTP_HOST is 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, setting SMTP_HOST is 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>"
  2. 02

    Email fails because a setting is missing

    In production, every send needs SMTP_HOST (your outgoing mail server, or SMTP relay) and SMTP_FROM. The app starts without them, but each send fails and names the missing setting.

    • At startup the app log has an email-config warning naming the setting
    • SMTP_FROM must look like EvenTier <no-reply@yourcompany.com>; quote it in the settings file
    • A sender on a reserved domain such as .local is rejected by mailbox providers, and the email_sender health check fails
    • Server install: ./install.sh --check lists a blank SMTP_HOST or SMTP_FROM
    Find the warningbash
    # Docker Compose
    docker compose logs app | grep email-config
    
    # Server
    journalctl -u eventier | grep email-config
  3. 03

    The mail server refuses the connection or the login

    EvenTier reaches your relay but can't connect or sign in to it. The smtp health check shows the relay's reply.

    • Port 587 uses STARTTLS; port 465 uses TLS from the start
    • Check SMTP_USER and SMTP_PASS, and that the relay may send for the SMTP_FROM domain
    • Docker Compose and Kubernetes: the test script below connects and signs in without sending anything
    • Add --to you@example.com in place of --verify-only to 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
  4. 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
  5. 05

    Links in email open the wrong address

    Links are built from NEXT_PUBLIC_APP_URL, or from NEXTAUTH_URL when that is unset.

    • Server: set NEXT_PUBLIC_APP_URL to the https address people open
    • Docker Compose builds it from EVENTIER_DOMAIN; Kubernetes from app.url
    • The app_url health check shows the address in use
    • A startup warning says when NEXT_PUBLIC_APP_URL is unset
  6. 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_INTEGRATIONS get “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=none is 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
    1. Admin → Settings → Organization settings → Channels
    2. Email channel enabled
  7. 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-secret header set to INBOUND_EMAIL_SECRET
    • A missing or wrong secret gets 401 “Inbound email secret is invalid.”
    • In production, an unset INBOUND_EMAIL_SECRET refuses 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>
  8. 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_INTEGRATIONS get “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
  9. 09

    Upload fails: “malware was detected”

    The scanner (ClamAV) flagged the file. The upload answers 422 MALWARE_DETECTED and 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. 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=scanner answers 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. 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_SCANNER must be clamav, or off on a self-hosted install
    • With clamav, CLAMAV_HOST and CLAMAV_PORT must point at clamd
    • Any other scanner name refuses every upload
    • off is honored only on self-hosted installs
    • Kubernetes: clamav.enabled: false alone turns scanning off on a self-hosted install
    • The scanner check of /api/health, and an attachment-config line 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. 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. 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. 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=off stay downloadable after scanning is turned back on
    • Ask for the file to be uploaded again, so it is scanned

Error codes

Codes returned by uploads, downloads and password reset, with the HTTP status.

CodeHTTPMeaningWhat to do
MALWARE_DETECTED422The scanner found malware; nothing was storedUpload the other files again without it
SCANNER_UNAVAILABLE503clamd is down, loading signatures, timed out or replied with an errorWait, then check clamd
SCANNER_NOT_CONFIGURED503Scanning is required but no usable scanner is setSet ATTACHMENT_MALWARE_SCANNER and CLAMAV_HOST / CLAMAV_PORT
ATTACHMENT_QUOTA_EXCEEDED413The workspace is at its attachment storage quotaSelf-hosted: raise ATTACHMENT_ORG_QUOTA_BYTES
ATTACHMENT_NOT_SCANNED403The file was stored without a scan, and scanning is now requiredUpload the file again
EMAIL_OFF409Password reset by email while email is turned offAn admin sets a new password

Good to know

  • Running without email? Leave EMAIL_DELIVERY_MODE=auto with SMTP_HOST blank, or set it to off: health checks and launch readiness then report it as a choice. Only smtp treats 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.