Zodiac Tech CRM Docs

Email & SMTP

Route workspace email through your own SMTP server — invites, password resets, OTP emails and scheduled reports — plus the platform-level default mailer.

admin super-admin Easy ⏱ 10 min Updated 2026-10-05

Email & SMTP

The CRM sends email for team invites, password resets, login OTP codes, notifications and scheduled report delivery. Each workspace can route all of that through its own SMTP server so mail comes from your domain — while the platform keeps a fallback mailer for installs that never configure one.

Who this is for

  • Admin setting up the workspace's outgoing email.
  • Super Admin configuring the platform default (or changing it in .env terms).

Difficulty: Easy · Time: about 10 minutes · Prerequisites:

  • SMTP credentials from your mail provider (host, port, username, password).
  • The workspace's plan includes the communications feature.

Step 1 — Enter your SMTP details (workspace)

  1. Go to Settings → Communication → Email.
  2. Fill in the form:
Field Notes
Host Required. e.g. smtp.yourprovider.com
Port Required. Default 587
Encryption TLS (typical), SSL, or None
Username Usually the full mailbox address
Password Write-only — stored encrypted, never shown again
From name What recipients see as the sender name
From email The sender address (must be allowed by your SMTP server)
  1. Click Save.

The password is write-only Once saved, the password field cannot be revealed — the CRM stores it encrypted. If you leave the field blank on a later save, the existing password is kept. If you need to replace it, paste the new one.

Step 2 — Send a test email

  1. Click Test email on the same page.
  2. The recipient defaults to your own account email — change it if you want to test another inbox.
  3. Expected result: the CRM sends a test message immediately; success or the provider's error is shown on the page.

Test email is blocked in demo mode On a demo install, credential saving and the test action are disabled by the platform's demo-mode guard — that is deliberate.

Step 3 — Know what uses this mailer

Sender Queued? Notes
Team invites No — sent immediately Invitee sets their own password via the email
Password reset Yes (ShouldQueue) Needs a running worker in production
Login email OTP No — sent immediately (login must not wait for a queue) See Firebase phone OTP
Notification digests / system mails Mostly queued Some billing/subscription mails implement ShouldQueue
Scheduled report delivery Runs hourly (reports:deliver) Delivered through the same mail path

So: with the local sync queue everything goes out inline; in production, run a worker or the queued mails sit in the jobs table — see Cron & queue workers.

Step 4 — Platform default (Super Admin)

If a workspace has not configured SMTP, the platform mailer is used. Platform defaults come from the server's .env (MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION, MAIL_FROM_ADDRESS, MAIL_FROM_NAME) and are editable without SSH from Super Admin → System → Script Settings, section "Outbound email (SMTP)".

  • Mailer choices: smtp, sendmail, log, array.
  • The default .env mailer on a fresh install is log — mail is written to the log file, not delivered. Change this before going live.

Which layer wins A workspace with settings.smtp.host set builds its own tenant_smtp mailer and mail.default points at it for that request. Workspaces without it fall through to the platform mailer. The tenant mailer is rebuilt (and purged) on every apply, so credential changes take effect immediately.

Expected result

Team invitations, password resets, OTP emails and report deliveries arrive from your configured address, and the test email succeeds from the workspace page. The demo/sandbox workspace story stays intact — nothing is sent to real customers during setup tests except your own test address.

Common mistakes

  • Port/encryption mismatch — 587 pairs with TLS, 465 with SSL; "None" only for unusual internal relays.
  • From email not allowed by the SMTP server — many providers reject a From address that is not a verified identity (550/553 errors).
  • Provider blocks the server's IP — check the provider's security log for the connection attempt.
  • Leaving the platform mailer as log on production — invites and resets go to a log file and nobody notices until a user complains.
  • No worker in production — queued mail (password resets, digests) never leaves the queue.

Troubleshooting

Symptom Likely cause Fix
Test email fails with connection error Wrong host/port, or outbound SMTP blocked by the host Verify credentials; ask the hosting provider to allow outbound 587/465
Test succeeds but invites don't arrive Invitations end up in spam, or queued mail stuck Check spam; ensure the worker runs
Auth error 535 Wrong username/password (or password never pasted since rotation) Re-paste the password and save
Mail sends from the wrong address Tenant From fields blank, falling back to platform defaults Set From name/email in the workspace
OTP email missing Workspace SMTP broken and platform fallback is log Fix SMTP; see Email or OTP not received

Technical details

  • App\Support\TenantSmtpManager builds the runtime mailer: config key tenant_smtp, transport smtp, port default 587, encryption default tls, timeout 30s, then sets mail.default and purges the mailer so reuse picks up new credentials.
  • Stored per tenant under settings.smtp (password encrypted) — no dedicated table.
  • Tenant UI: EmailSettingsPage (Settings → Communication group), gated by the communications plan feature.
  • Super Admin UI: ScriptSettings page (navigation label "Script Settings", group System) — writes .env values through the EnvEditor.
  • Fresh-install default mailer is log; production should set smtp (directly or via Script Settings).

Was this page helpful?