Email Setup

Configure outbound email to enable user invitations, password resets, email verification, and email OTP codes.

Why Email?

Email configuration enables:

• User Invitations - Invite users via email from the Admin Panel
• Password Reset - Allow users to reset forgotten passwords
• Email Verification - Verify new user email addresses (optional)
• Email OTP - Send two-factor authentication codes by email

Without Email

If email is not configured:

• The "Invite User" button will be hidden in the Admin Panel
• A message will explain that email configuration is required
• Password reset functionality will be unavailable
• Email OTP cannot be used for two-factor authentication

Choose a Provider

BillManager supports provider-neutral outbound email:

• SMTP - Recommended for self-hosted installs. Use your mail provider, transactional SMTP service, or an existing relay.
• Resend - Supported for hosted or existing installs that already use RESEND_API_KEY.
• None - Leave email disabled.

Production SMTP Server

BillManager does not bundle a production SMTP server. Running one safely requires DNS, SPF/DKIM/DMARC, abuse prevention, delivery monitoring, and network port planning. Use a mail provider, transactional email service, or relay you already operate.

Setting Up SMTP

Use SMTP with providers such as Fastmail, Gmail SMTP, Mailgun, Amazon SES SMTP, or a local relay.

1. Gather SMTP Settings

From your mail provider or relay, collect:

• SMTP host
• Port (587 with STARTTLS is most common, 465 for implicit SSL)
• Username and password, if authentication is required
• Sender address for BillManager emails

2. Configure BillManager

Add these environment variables to your docker-compose.yml or .env file:

environment:
  - EMAIL_PROVIDER=smtp
  - SMTP_HOST=smtp.example.com
  - SMTP_PORT=587
  - SMTP_USERNAME=your-smtp-username
  - SMTP_PASSWORD=your-smtp-password
  - SMTP_USE_TLS=true
  - SMTP_USE_SSL=false
  - SMTP_TIMEOUT=10
  - [email protected]
  - APP_URL=https://bills.yourdomain.com

For an unauthenticated internal relay, omit SMTP_USERNAME and SMTP_PASSWORD:

environment:
  - EMAIL_PROVIDER=smtp
  - SMTP_HOST=mail-relay.local
  - SMTP_PORT=25
  - SMTP_USE_TLS=false
  - SMTP_USE_SSL=false
  - [email protected]
  - APP_URL=https://bills.yourdomain.com

Variable	Description	Default
EMAIL_PROVIDER	smtp, resend, or none	Auto-detects Resend/SMTP config
SMTP_HOST	SMTP hostname	None
SMTP_PORT	SMTP port	587 or 465 when SSL is enabled
SMTP_USERNAME	SMTP username, optional for relays	None
SMTP_PASSWORD	SMTP password, optional for relays	None
SMTP_USE_TLS	Use STARTTLS	true unless SSL is enabled
SMTP_USE_SSL	Use implicit SSL/TLS	false
SMTP_TIMEOUT	Connection timeout in seconds	10
FROM_EMAIL	Sender email address	[email protected]
APP_URL	Your BillManager URL for email links	http://localhost:5000

3. Restart BillManager

docker-compose restart billmanager

Setting Up Resend

Resend remains supported. Use it if you already have a Resend account or prefer an API-based transactional provider.

1. Create a Resend Account

1. Go to resend.com and sign up
2. Verify your email address
3. Navigate to API Keys in the dashboard

2. Create an API Key

1. Click "Create API Key"
2. Give it a name (e.g., "BillManager Production")
3. Select "Full access" permissions
4. Copy the API key (starts with re_)

3. Add Domain (Recommended)

For production, add and verify your domain:

1. Go to Domains in Resend
2. Add your domain (e.g., yourdomain.com)
3. Add the DNS records Resend provides
4. Wait for verification

4. Configure BillManager

Add these environment variables:

environment:
  - EMAIL_PROVIDER=resend
  - RESEND_API_KEY=re_your_api_key_here
  - [email protected]
  - APP_URL=https://bills.yourdomain.com

Variable	Description
EMAIL_PROVIDER	Set to resend for explicit Resend selection
RESEND_API_KEY	Your Resend API key
FROM_EMAIL	The sender email address (must be from your verified domain in production)
APP_URL	Your BillManager URL (used in email links)

Backward Compatibility

Existing installs with only RESEND_API_KEY continue to work. New self-hosted installs should set EMAIL_PROVIDER explicitly.

Testing Email

After configuration, test that emails work:

1. Log in as admin
2. Go to Admin → Users
3. Click "Invite User"
4. Enter your own email address
5. Check that you receive the invitation

Troubleshooting

"Invite User" Button Not Visible

• EMAIL_PROVIDER is none, missing, or points to an incomplete provider config
• For SMTP, SMTP_HOST is missing or only one of SMTP_USERNAME / SMTP_PASSWORD is set
• For Resend, RESEND_API_KEY is missing or invalid
• Restart the container after adding the environment variable

Emails Not Received

1. Check BillManager logs for provider errors
2. Verify FROM_EMAIL is allowed by your SMTP provider or verified Resend domain
3. Check spam/junk folders
4. Verify APP_URL is correct (links in emails use this)
5. For SMTP, confirm TLS/SSL and port settings match your provider

SMTP Authentication Fails

• Confirm the username/password are correct
• For Gmail, use an app password instead of your regular password
• Confirm whether your provider expects STARTTLS on port 587 or SSL on port 465
• Check whether the provider restricts the sender address

Invalid Resend API Key

• Ensure the key starts with re_
• Check for extra whitespace when copying
• Verify the key hasn't been revoked in Resend dashboard