Email configuration

Overview

VerifyWise uses email for account-related communications such as user invitations, password resets, and verification emails. For self-hosted deployments, you need to configure an email provider to enable these features.

VerifyWise supports multiple email providers to accommodate different infrastructure requirements. Choose the provider that best fits your organization's existing setup and security requirements.

Supported providers

The following email providers are supported:

• Resend: Recommended for development and small deployments. Simple API-based setup.
• Generic SMTP: Works with Gmail, Outlook, Yahoo, and custom mail servers.
• Exchange Online: For organizations using Microsoft 365.
• Exchange On-Premises: For self-hosted Microsoft Exchange environments.
• Amazon SES: For AWS-based deployments and high-volume sending.

Core settings

All email configurations require these environment variables:

• EMAIL_PROVIDER: The provider to use: resend, smtp, exchange-online, exchange-onprem, or amazon-ses
• EMAIL_ID: The verified sender email address. Must match a domain verified with your provider.

Resend

Resend is the simplest option to configure and is recommended for development environments and smaller deployments. You will need to create a Resend account and verify your sending domain.

Required environment variables:

EMAIL_PROVIDER=resend
EMAIL_ID=notifications@yourdomain.com
RESEND_API_KEY=re_your_api_key_here

To get your API key, sign up at resend.com, add your domain, and generate an API key from the dashboard.

Generic SMTP

The SMTP provider works with any standard mail server including Gmail, Outlook, Yahoo, and custom servers. For providers that require two-factor authentication, you will need to generate an app password.

Required environment variables:

EMAIL_PROVIDER=smtp
EMAIL_ID=notifications@yourdomain.com
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_SECURE=false

Common SMTP server settings:

• Gmail: smtp.gmail.com, port 587, SMTP_SECURE=false
• Outlook: smtp.office365.com, port 587, SMTP_SECURE=false
• Yahoo: smtp.mail.yahoo.com, port 587, SMTP_SECURE=false

Exchange Online (Microsoft 365)

For organizations using Microsoft 365, Exchange Online provides enterprise-grade email delivery. This configuration uses app passwords for authentication rather than account passwords.

Required environment variables:

EMAIL_PROVIDER=exchange-online
EMAIL_ID=notifications@yourcompany.com
EXCHANGE_ONLINE_USER=service-account@yourcompany.com
EXCHANGE_ONLINE_PASS=your-app-password-here

To set up Exchange Online:

1. Create a dedicated service account in Microsoft 365
2. Enable app passwords for the service account
3. Generate an app password from the Microsoft account security settings
4. Use the app password in the EXCHANGE_ONLINE_PASS variable

Exchange On-Premises

For organizations with self-hosted Microsoft Exchange servers, the on-premises configuration provides additional options for authentication and TLS certificates.

Required environment variables:

EMAIL_PROVIDER=exchange-onprem
EMAIL_ID=notifications@yourcompany.com
EXCHANGE_ONPREM_HOST=mail.yourcompany.com
EXCHANGE_ONPREM_PORT=587
EXCHANGE_ONPREM_USER=serviceaccount
EXCHANGE_ONPREM_PASS=password
EXCHANGE_ONPREM_DOMAIN=YOURCOMPANY
EXCHANGE_ONPREM_SECURE=false
EXCHANGE_ALLOW_SELF_SIGNED=false
EXCHANGE_CUSTOM_CA_PATH=/etc/ssl/certs/company-ca.pem

Configuration options:

• EXCHANGE_ONPREM_DOMAIN: Your Active Directory domain name
• EXCHANGE_ONPREM_SECURE: Set to true if your server requires SSL from the start
• EXCHANGE_ALLOW_SELF_SIGNED: Set to true only if using self-signed certificates (not recommended for production)
• EXCHANGE_CUSTOM_CA_PATH: Path to your organization's CA certificate if using internal PKI

Amazon SES

Amazon Simple Email Service is ideal for AWS-based deployments and high-volume email sending. You will need to verify your sending domain and request production access if you are in the SES sandbox.

Required environment variables:

EMAIL_PROVIDER=amazon-ses
EMAIL_ID=notifications@yourdomain.com
AWS_SES_REGION=us-east-1
AWS_SES_ACCESS_KEY_ID=AKIA...
AWS_SES_SECRET_ACCESS_KEY=your-secret-key
AWS_SES_API_VERSION=2010-12-01

Optional settings:

• SES_CONFIGURATION_SET: Name of an SES configuration set for tracking and monitoring
• AWS_CREDENTIAL_REFRESH_INTERVAL_MS: Interval for credential rotation in milliseconds (default: 3600000 / 1 hour)

To set up Amazon SES:

1. Verify your sending domain in the SES console
2. Request production access if still in sandbox mode
3. Create an IAM user with ses:SendEmail and ses:SendRawEmail permissions
4. Generate access keys for the IAM user

Security considerations

VerifyWise implements several security measures for email sending:

• TLS enforcement: All providers use TLS 1.2 or higher for encrypted connections
• Input validation: Email addresses and content are validated to prevent header injection attacks
• Credential security: All credentials must be stored in environment variables, never in code
• Certificate validation: Custom CA certificates for on-premises Exchange are validated for path traversal

Production checklist

Before deploying to production, verify the following:

• Sending domain is verified with your email provider
• Using a dedicated service account rather than personal credentials
• App passwords are used instead of account passwords where applicable
• Credentials are stored in environment variables only
• TLS is enabled for SMTP connections (SMTP_SECURE or STARTTLS)
• Service account has minimal required permissions
• Tested email delivery by triggering a password reset or invitation

Troubleshooting

VerifyWise validates email configuration on startup and logs the results. Check the application logs if emails are not being delivered.

Common issues:

• Authentication failed: Verify credentials are correct and app passwords are used if 2FA is enabled
• Domain not verified: Ensure the EMAIL_ID domain is verified with your provider
• Connection refused: Check firewall rules and verify the SMTP host and port are correct
• TLS errors: Verify TLS settings match your server requirements
• SES sandbox: Request production access if emails only reach verified addresses