Email Provider

EdgeBase uses an external email provider to send transactional emails — verification codes, password resets, magic links, and email-change verification messages. Configure your provider in edgebase.config.ts.

Configuration

import { defineConfig } from '@edgebase/shared';

export default defineConfig({
  email: {
    provider: 'resend',
    apiKey: process.env.EMAIL_API_KEY,
    from: 'noreply@my-app.com',
    appName: 'My App',                                    // Optional
    verifyUrl: 'https://my-app.com/verify?token={token}', // Optional
    resetUrl: 'https://my-app.com/reset?token={token}',   // Optional
    magicLinkUrl: 'https://my-app.com/magic?token={token}', // Optional
    emailChangeUrl: 'https://my-app.com/verify-email-change?token={token}', // Optional
  },
});

Field	Type	Required	Description
provider	string	✅	'resend' | 'sendgrid' | 'mailgun' | 'ses'
apiKey	string	✅	API key from your email provider
from	string	✅	Sender email address (must be verified with provider)
domain	string	Mailgun only	Mailgun sending domain
region	string	SES only	AWS region (e.g. 'us-east-1')
appName	string	—	Display name shown in email templates (e.g. "My App")
verifyUrl	string	—	Custom email verification URL. Use {token} as placeholder
resetUrl	string	—	Custom password reset URL. Use {token} as placeholder
magicLinkUrl	string	—	Default magic link URL. Use {token} as placeholder
emailChangeUrl	string	—	Default email-change verification URL. Use {token} as placeholder

These templates are default fallbacks. For magic link, password reset, and email change, clients can override them per request with redirectUrl or redirectTo. EdgeBase appends token, type, and optional state to that request-specific URL.

If you want to restrict request-specific redirects, configure auth.allowedRedirectUrls.

No email provider?

If email is not configured, EdgeBase cannot deliver transactional emails. Email-driven flows can still generate action tokens for testing, but production apps should configure a provider.

Supported Providers

Resend (Recommended)

Best developer experience with the most generous free tier.

email: {
  provider: 'resend',
  apiKey: 're_xxxxxxxxxx',
  from: 'noreply@my-app.com',
},

• Free tier: 3,000 emails/month
• Setup: resend.com → Create API Key → Verify domain
• Docs: resend.com/docs

Resend current behavior

As of March 8, 2026, Resend does not require production approval. You can create an API key and send immediately.

Default resend.dev domain is test-only

Resend's default onboarding@resend.dev sender can only send to the email address associated with your own Resend account. To send magic links, password resets, or verification emails to other recipients, you must add and verify your own domain and use a from address on that verified domain.

Use a subdomain for sending

Resend recommends verifying a subdomain such as auth.example.com or mail.example.com instead of your root domain. This keeps your transactional-email reputation isolated and makes the sender purpose clearer.

SendGrid

Most widely used transactional email service.

email: {
  provider: 'sendgrid',
  apiKey: 'SG.xxxxxxxxxx',
  from: 'noreply@my-app.com',
},

• Free tier: 100 emails/day
• Setup: sendgrid.com → Settings → API Keys
• Docs: docs.sendgrid.com

SendGrid smoke prerequisites

For local smoke tests, you still need a verified sender. Twilio SendGrid supports Single Sender Verification for quick testing and Domain Authentication for full production sending. Use a verified from address before testing magic links, verification emails, or password resets.

Mailgun

European data sovereignty option with region selection.

email: {
  provider: 'mailgun',
  apiKey: 'key-xxxxxxxxxx',
  from: 'noreply@my-app.com',
  domain: 'mg.my-app.com',  // Required for Mailgun
},

• Free tier: 1,000 emails/month (first 3 months)
• Setup: mailgun.com → Sending → Domains → API Keys
• Docs: documentation.mailgun.com

Mailgun smoke prerequisites

Mailgun smoke tests require a verified sending domain. Set domain to the Mailgun domain you configured, and make sure from uses that same domain.

AWS SES

Lowest cost at scale for high-volume senders.

email: {
  provider: 'ses',
  apiKey: 'AKIA...:secretKey',  // accessKeyId:secretAccessKey[:sessionToken]
  from: 'noreply@my-app.com',
  region: 'us-east-1',  // Required for SES
},

• Pricing: $0.10 per 1,000 emails
• Setup: AWS Console → SMTP Settings
• Docs: docs.aws.amazon.com/ses

SES smoke prerequisites

SES HTTP API requests must be AWS SigV4-signed. EdgeBase expects apiKey in the form accessKeyId:secretAccessKey[:sessionToken] and signs the request for you.

SES sandbox restrictions

If your AWS account is still in the SES sandbox, you may need to verify both the sender and the recipient email address before any smoke test mail can be delivered.

Provider Comparison

Provider	Free Tier	Best For
Resend	3,000/month	Most projects (recommended default)
SendGrid	100/day	Teams already using SendGrid
Mailgun	1,000/month (3mo)	EU data residency requirements
AWS SES	Pay-as-you-go	High-volume (100K+ emails/month)

What Emails Are Sent?

EdgeBase sends transactional emails for these auth flows:

Flow	Trigger	Template
Email Verification	User signs up with email/password	Verification code link
Password Reset	User requests password reset	Reset token link
Magic Link	User requests passwordless sign-in	One-time sign-in link
Email Change	Signed-in user requests email change	Verify new-email link

Email templates are built-in and include responsive HTML styling. Custom template support is planned for a future release.

Local Harness Mailbox-Click Tests

The local JS web harness separates capability validation from mailbox-click validation.

• Run Email Validation
  • Tests the current signed-in email account's password/session/TOTP/passkey capabilities
  • Does not automatically click or complete email inbox links
• Send Verify Email
• Send Password Reset Email
• Send Change Email Link
  • These three are the mailbox-click tests

Current local callback targets used by the harness:

• Magic link: http://localhost:4173/auth/magic?token=...&type=magic-link
• Verify email: http://localhost:4173/auth/verify-email?token=...&type=verify
• Password reset: http://localhost:4173/auth/reset-password?token=...&type=password-reset
• Change email: http://localhost:4173/auth/change-email?token=...&type=email-change

When these links are opened in the harness, EdgeBase verifies the token and the harness updates the signed-in session automatically where possible.

Smoke Test Strategy Across Providers

For Resend / SendGrid / Mailgun / SES, reuse the same harness buttons instead of making provider-specific clients:

1. Configure the provider in edgebase.config.ts
2. Restart the local EdgeBase dev server
3. Sign in to the harness with the mailbox you want to test
4. Send verification / password reset / change-email mail
5. Confirm inbox delivery and click the link

That means:

• one provider is enough to prove the auth flow
• each additional provider should at least pass mail acceptance + inbox-click smoke

Cloudflare Email Sending (Coming Soon)

Cloudflare announced the Email Sending Service in late 2025 (currently in private beta). When it reaches GA, EdgeBase will support provider: 'cloudflare' as a native option:

• ✅ No API key needed — works with your Cloudflare domain automatically
• ✅ Auto DNS setup — SPF, DKIM, DMARC configured automatically
• ✅ Native Workers binding — minimal latency, no external HTTP calls
• ✅ Zero config for Edge deployments — just npx edgebase deploy

// Coming when Cloudflare Email Sending reaches GA
email: {
  provider: 'cloudflare',
  from: 'noreply@my-app.com',
  // No apiKey needed!
},

Private Beta

The Cloudflare Email Sending Service is currently in private beta. Use one of the HTTP REST providers above until it reaches general availability.

Self-Hosting (Docker)

When self-hosting with Docker, the same email configuration works identically. All four HTTP REST providers are fully supported in the Docker environment.

// Works the same in Docker
email: {
  provider: 'resend',
  apiKey: process.env.EMAIL_API_KEY,
  from: 'noreply@my-app.com',
},