Skip to main content
iWorkWhen can send emails for approvals, trade requests, password resets, and schedule publishes. You point it at your org’s SMTP server; the app stores the password encrypted (AES-256-GCM) at rest and decrypts server-side only when sending.

​
Where

Path: /app/admin/smtp.

​
Fields

​
host
string
SMTP server hostname. Exchange 365: smtp.office365.com. Gmail: smtp.gmail.com.
​
port
number
default:"587"
Typical ports: 587 for STARTTLS, 465 for SSL, 25 for legacy plain.
​
secure
boolean
default:"false"
Check for SSL/TLS (port 465). Leave unchecked for STARTTLS (port 587) — that’s the Exchange 365 default.
​
username
string
SMTP auth username. Usually the full mailbox email address.
​
password
string
SMTP auth password. For mailboxes with MFA: create an app password. Leave blank on edit to keep the existing password.
​
from_address
string
Envelope sender. Must match your SMTP auth’s allowed senders. Usually same as username.
​
from_name
string
Display name shown before the email in recipients’ clients. E.g. “iWorkWhen Scheduling”.
​
reply_to
string
Optional — if set, replies go here instead of from_address.
​
enabled
boolean
default:"false"
Master switch. If off, the app skips sending emails (no error).

​
Exchange 365 quick-setup

1

Host / Port / TLS

smtp.office365.com / 587 / Secure unchecked (STARTTLS, not SSL).
2

Username / Password

Username: full Exchange email. Password: mailbox password OR — if MFA is on — an app password (Microsoft 365 Admin Center → Users → Active users → [mailbox] → Mail → Manage email apps → Create app password).
3

From

From address = username. From name = “iWorkWhen” or similar.
4

Enable and Save

Check Enable outbound email, click Save settings.
5

Send test

Enter your email in the Send test box, click Send test. Expect to get “If you got this, SMTP is working!” in your inbox within 15 seconds.

​
”SmtpClientAuthentication is disabled”

Microsoft disables SMTP AUTH by default on new Exchange 365 tenants. Enable it:
  • Tenant level: Exchange Admin Center → Settings → Mail flow → Turn off SMTP AUTH protection for this organization (set to unchecked).
  • Mailbox level: Microsoft 365 Admin Center → Active users → [mailbox] → Mail → Manage email apps → check Authenticated SMTP.
Both need to be enabled. Save and retry the test send.

​
How the password is stored

  1. You enter it in the form.
  2. The app encrypts it server-side using AES-256-GCM with a key held in an environment variable (IW_ENCRYPTION_KEY).
  3. Only the encrypted ciphertext is stored in the database.
  4. When sending, the server decrypts in memory and passes to nodemailer.
The password is never exposed to the browser, never logged, and can’t be retrieved by querying the database.

​
Events that trigger email

Out of the box:
  • Trade request created (to the target)
  • Trade approved / denied (to both parties)
  • Absence request created (to approvers)
  • Absence approved / denied (to the requester)
  • OT volunteer selected (to the selected user)
  • Password reset requested (via the recovery link flow)
Future: schedule publish, bidding round opens, etc.

​
Required permission

smtp.manage — Admin only by default.

​
Troubleshooting

Either: (a) SMTP AUTH is disabled at the tenant or mailbox level — enable it via the Microsoft 365 Admin Center; (b) the password is wrong; (c) MFA is on and you need an app password instead of the regular password.
Check the Enable outbound email checkbox is on, and you’ve clicked Save. Also verify host/username/password are filled.
Approvals do fire sendMail() but silently swallow errors so the DB action doesn’t fail. Check the Vercel function logs for the real error — typically auth or a network block.