Home / Help / Reference

Email delivery setup

Microsoft 365 (@nsva.org) SMTP, env vars, workflow mailboxes, and leadership handoff.

← Site guide overview

The site sends transactional mail using SMTP (Microsoft 365). Production standard for NSVA is sending from @nsva.org addresses. These flows send mail when configured:

  • MFA email OTP, email verification, password-related notices
  • Membership application receipts and admin review outcomes
  • Store / payment confirmations, calendar registration, island transfers, duty station requests, newsletters (admin), etc.

1. Production — Microsoft 365 (@nsva.org)

Use the organization’s M365 tenant: create or designate a mailbox (for example noreply@nsva.org) for application mail, enable SMTP AUTH if your policy requires it, and store credentials in Secret Manager.

Set in the hosting environment (not committed):

NODE_ENV=production
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=noreply@nsva.org
SMTP_PASS=<mailbox or app password per tenant policy>
EMAIL_FROM="NSVA <noreply@nsva.org>"
APP_URL=https://nsva.org
NEXTAUTH_URL=https://nsva.org
  • EMAIL_PROVIDER must be smtp when using M365 so the application uses SMTP and not an alternate mail transport.
  • Do not set EMAIL_OVERRIDE_TO in production — it would redirect member mail to one inbox.

Dedicated sending account (noreply@nsva.org)

Use a single mailbox (e.g. noreply@nsva.org) for all application From mail. Store credentials only in Secret Manager (production) or a local .env.local (development)—never commit passwords or paste them into tickets.

Microsoft 365 (tenant admin)

  1. Confirm the mailbox exists and is allowed to send.
  2. Enable SMTP AUTH (Authenticated SMTP) for that mailbox if your org allows it (some tenants disable SMTP or require an app password instead of the primary password when MFA applies—follow your IT policy).
  3. If sign-in or SMTP fails after correct credentials, ask the admin to check Conditional Access and security defaults for SMTP clients.

Google Cloud Run (production)

The deploy configuration expects these Secret Manager names (mapped to env vars on the service):

Secret Maps to Example value
nsva-smtp-user SMTP_USER noreply@nsva.org
nsva-smtp-pass SMTP_PASS (mailbox or app password—secret only)
nsva-email-from EMAIL_FROM NSVA <noreply@nsva.org>

SMTP_HOST, SMTP_PORT, and SMTP_SECURE are set in Cloud Build (smtp.office365.com, 587, false). After creating or rotating secrets, deploy a new revision so Cloud Run loads the updated values.

Verify

  • Prefer a controlled test via your environment’s policy (ALLOW_TEST_EMAIL and GET /api/test-email?to=... where allowed), or exercise a real flow (e.g. password reset) after deploy.
  • On failure, check hosting logs for [EmailService] SMTP failed:.

Auth model

The application uses SMTP with username and password (basic auth) as shown above. OAuth / modern auth for SMTP is not implemented in the codebase today; if Microsoft requires OAuth long term, that would be a separate integration effort.

Workflow / office recipients (SOP “To” addresses)

National office workflow routing uses a configurable list of role addresses — defaults use @nsva.org. Override per role with NSVA_OFFICE_EMAIL_<KEY> if an inbox uses a different alias:

NSVA_OFFICE_EMAIL_MEMBERSHIP_CHAIR=Membership@nsva.org
NSVA_OFFICE_EMAIL_SECRETARY=Secretary@nsva.org
NSVA_OFFICE_EMAIL_TREASURER=Treasurer@nsva.org
NSVA_OFFICE_EMAIL_EVENTS_COORDINATOR=EventsCoordinator@nsva.org
NSVA_OFFICE_EMAIL_COMMANDER=National.commander@nsva.org
NSVA_OFFICE_EMAIL_FUNDRAISING=Fundraising@nsva.org
NSVA_OFFICE_EMAIL_SHIPS_STORE=Ships.store@nsva.org
NSVA_OFFICE_EMAIL_SPONSORSHIP=Sponsorship@nsva.org
NSVA_OFFICE_EMAIL_PUBLIC_AFFAIRS=PublicAffairs@nsva.org
NSVA_OFFICE_EMAIL_CONVENTION_CHAIR=ConventionChair@nsva.org

Add more NSVA_OFFICE_EMAIL_* variables if your organization adds workflows beyond the defaults.

Inbound mail

Receiving replies at role addresses requires MX and mailbox configuration in Microsoft 365 (or your mail host). Transactional From: is separate from where members reply; set Reply-To in product flows when a specific office inbox should receive replies.

Email routing and in-app notifications

  • Office mailboxes: Workflow “To:” lists follow the national routing configuration (override with NSVA_OFFICE_EMAIL_* when needed).
  • In-app alerts: Admin notifications complement email for queues and approvals.
  • Roles: Assign or revoke capabilities in Admin → Roles (/admin/roles).

2. Other SMTP providers

Any provider that offers SMTP works with EMAIL_PROVIDER=smtp and the matching host, port, TLS, user, and password. Use the same variable names in Google Secret Manager (or your host’s secret store) as for Microsoft 365.

3. Verify configuration

Use the operator test route where permitted (see environment policy for ALLOW_TEST_EMAIL):

GET /api/test-email?to=recipient@example.com

Confirm delivery and that From matches EMAIL_FROM. Check hosting logs for [EmailService] lines if sending fails.

4. Common issues

Symptom What to check
Authentication or relay errors SMTP AUTH enabled on the mailbox? Correct user/password or app password per tenant policy?
Wrong “from” EMAIL_FROM matches the mailbox or allowed sender in M365
Links wrong in emails APP_URL / NEXTAUTH_URL match the public site URL

5. Leadership transition (shared inbox + forwarding)

Role-based “To:” addresses stay stable when individuals change. When leadership turns over:

  1. Update in-app access — Admin → Roles for incoming/outgoing officers.
  2. Update shared mailbox access in Microsoft 365 for each office inbox.
  3. Keep forwarding intentional — Prefer role aliases over personal addresses.
  4. Verify sending only according to your organization’s policy for operational test messages.