Bring-Your-Own (BYO) Email Providers

Deliver magic links, invitations, and password resets from your own custom domain using Resend, Postmark, Amazon SES, or custom SMTP.

Why custom email providers matter

Transactional authentication emails (magic link login codes, password resets, organization invitations) are among the most critical touchpoints in your user journey. Using a shared generic email provider causes two major problems:

  • Deliverability and Spam Risk: Shared sender IPs can be degraded by unrelated senders, causing login links to land in spam folders.
  • Brand Trust and Phishing Protection: Users expect emails to arrive from [email protected], not a third-party platform address.

HVT allows each project to configure its own isolated email provider with dedicated domain reputation, custom sender headers, and automated error handling.

Supported providers

HVT provides native first-class integrations with the leading email infrastructure providers:

Provider ValuePlatformRequired Fields
resendResend APIapi_key (re_...), from_email
postmarkPostmark Server APIapi_key (Server API token), from_email
sesAmazon SESaws_region, aws_access_key_id, aws_secret_access_key, from_email
smtpCustom SMTP Serversmtp_host, smtp_port, smtp_username, smtp_password, from_email
system_defaultHVT Platform MailerNone (default fallback)

Zero plaintext leakage: Encryption at rest

All provider secrets (api_key, smtp_password, aws_secret_access_key) are encrypted at rest using AES-128-CBC via Django MultiFernet cryptography.

Credential Redaction Invariant
API response payloads never return secret credentials in plaintext. Instead, GET responses return boolean existence flags: has_api_key, has_smtp_password, and has_aws_secret_access_key.

Inspect current email settings

Fetch the current email configuration for a specific project:

bash
# Inspect current email provider configuration
GET /api/v1/organizations/current/projects/b5540592-38fd-4d42-9538-c125716f31f4/email-config/
Authorization: Bearer <org_admin_token>

# Response (200 OK)
{
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "project": "b5540592-38fd-4d42-9538-c125716f31f4",
  "provider": "resend",
  "from_email": "[email protected]",
  "from_name": "MyCompany Auth",
  "is_active": true,
  "has_api_key": true,
  "has_smtp_password": false,
  "has_aws_secret_access_key": false,
  "smtp_host": "",
  "smtp_port": 587,
  "smtp_username": "",
  "smtp_use_tls": true,
  "smtp_use_ssl": false,
  "aws_region": "",
  "aws_access_key_id": "",
  "created_at": "2026-10-15T12:00:00Z",
  "updated_at": "2026-11-09T09:30:00Z"
}

Configuration recipes by provider

Update your project's email provider settings using a PATCH request:

1. Resend

bash
# Configure Resend API
PATCH /api/v1/organizations/current/projects/b5540592-38fd-4d42-9538-c125716f31f4/email-config/
Authorization: Bearer <org_admin_token>
Content-Type: application/json

{
  "provider": "resend",
  "from_email": "[email protected]",
  "from_name": "MyBrand Security",
  "api_key": "re_123456789_abcdefghijklmnopqrstuvwxyz"
}

2. Postmark

bash
# Configure Postmark API
PATCH /api/v1/organizations/current/projects/b5540592-38fd-4d42-9538-c125716f31f4/email-config/
Authorization: Bearer <org_admin_token>
Content-Type: application/json

{
  "provider": "postmark",
  "from_email": "[email protected]",
  "from_name": "MyBrand Login",
  "api_key": "25a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

3. Amazon SES

bash
# Configure Amazon SES
PATCH /api/v1/organizations/current/projects/b5540592-38fd-4d42-9538-c125716f31f4/email-config/
Authorization: Bearer <org_admin_token>
Content-Type: application/json

{
  "provider": "ses",
  "from_email": "[email protected]",
  "from_name": "MyBrand Notifications",
  "aws_region": "us-east-1",
  "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

4. Custom SMTP

bash
# Configure Custom SMTP Server
PATCH /api/v1/organizations/current/projects/b5540592-38fd-4d42-9538-c125716f31f4/email-config/
Authorization: Bearer <org_admin_token>
Content-Type: application/json

{
  "provider": "smtp",
  "from_email": "[email protected]",
  "from_name": "Internal Enterprise Auth",
  "smtp_host": "smtp.internal.company.com",
  "smtp_port": 587,
  "smtp_username": "smtp_service_user",
  "smtp_password": "ultra_secure_smtp_password",
  "smtp_use_tls": true,
  "smtp_use_ssl": false
}

Testing email delivery

Before activating your email configuration in production, use the test endpoint to send a verification message. This validates DNS SPF/DKIM alignment, API credentials, and SMTP handshakes without triggering real user events:

bash
# Send a test email verification to confirm deliverability
POST /api/v1/organizations/current/projects/b5540592-38fd-4d42-9538-c125716f31f4/email-config/test/
Authorization: Bearer <org_admin_token>
Content-Type: application/json

{
  "to_email": "[email protected]"
}

# Response (200 OK)
{
  "detail": "Test email sent successfully.",
  "provider": "resend",
  "to_email": "[email protected]"
}