Support Email Provider Configurations via API with multi-providers and async/sync sending modes

[UdeshAthukorala]

Problem Description

Currently, Thunder supports SMS provider configuration through a well-designed API (/notification-senders/message) with full CRUD operations and support for multiple providers (Twilio, Vonage, Custom). However, email provider configuration does not have the same level of support. The current email implementation has the following limitations:

1. No API support

Email is configured exclusively through the email.smtp section of deployment.yaml. There is no REST API to create, update, list, or delete email providers at runtime. This means any change to email configuration requires modifying the config file and restarting the server.

2. Only support SMTP based Email Providers (No HTTP-based email provider support)

The current implementation only supports the SMTP transport (backend/internal/system/email/smtp_client.go). Many modern email services expose HTTP APIs (SendGrid, Amazon SES API, Mailgun, Postmark, Azure Communication Services) that are often preferred for cloud-native deployments. Thunder has no way to integrate with these.

3. Only supports Synchronous delivery

The current emailExecutor sends emails synchronously within the flow execution pipeline. There is no option for asynchronous dispatch. This creates two problems:

• Latency in user-facing flows - Slow SMTP servers or rate-limited APIs block the authentication/registration flow.
• No flexibility for customers- Some scenarios (e.g., Email OTP) genuinely require synchronous delivery with immediate confirmation, while others (e.g., user invitations, welcome emails) should not block the flow.

4. Only support a single provider instance - (Low Priority)

Only one email configuration is supported at a time, and there is no way to configure multiple email providers. If there is a service degradation in the configured email provider, there is no ability to easily switch over to a secondary email provider. There is also no concept of a "default" provider that can be seamlessly overridden when needed.

Proposed Solution

1. Email Provider Management API

Introduce a new set of endpoints under /notification-senders/email, following the same pattern as the existing /notification-senders/message API:

Method	Endpoint	Description
GET	/notification-senders/email	List all email providers
POST	/notification-senders/email	Create a new email provider
GET	/notification-senders/email/{id}	Get an email provider by ID
PUT	/notification-senders/email/{id}	Update an email provider
DELETE	/notification-senders/email/{id}	Delete an email provider
PATCH	/notification-senders/email/{id}/default	Set a provider as default

These endpoints should be secured with OAuth2 system scope, consistent with the existing notification sender API.

2. Multiple Provider Types: SMTP and HTTP

The email provider model should support two provider types, mirroring how SMS already supports Twilio, Vonage, and Custom:

Provider Type	Transport	Properties	Use Cases
smtp	SMTP protocol (STARTTLS/TLS)	host, port, username, password, from_address, enable_start_tls, enable_authentication	Gmail, Microsoft 365, self-hosted mail servers, any SMTP relay
http	HTTP/HTTPS REST API	url, http_method, http_headers, content_type, payload_template	SendGrid, Amazon SES (API), Mailgun, Postmark, Azure Communication Services, any custom HTTP endpoint

3. Synchronous and Asynchronous Email Delivery

Different customers require different delivery semantics. The system should support both modes:

Synchronous (blocking):

• Email is sent inline during request/flow execution.
• Caller receives confirmation or error before the response returns.
• When to use: Email OTP verification, security-critical notifications, any flow that must confirm delivery before proceeding.

Asynchronous (non-blocking):

• Email is queued for background delivery; the flow continues immediately.
• Caller receives an acknowledgment that the email was accepted, not that it was delivered.
• When to use: User invitations, welcome emails, password reset links, bulk notifications — any scenario where the flow should not block on email delivery.

The delivery mode should be configurable per-provider.

# Provider-level default
delivery_mode: "async"   # "sync" | "async"

# Async-specific settings
async:
  worker_pool_size: 10
  retry_max_attempts: 3
  retry_backoff_base_ms: 1000

4. Multiple Email Providers with Default Selection

The system should support configuring multiple email providers simultaneously, with one designated as the default. A hard limit can be defined for the maximum number of email providers that can be configured per organization.

• One default provider - Exactly one email provider can be marked as is_default: true. Setting a new default automatically unsets the previous one.
• Explicit provider selection - If there is a service degradation in the default email provider, organization admins should be able to easily switch over to a secondary email provider without requiring a server restart or redeployment.
• Fallback to static config - If no API-managed providers exist, the system falls back to the existing deployment.yaml SMTP configuration for backward compatibility.