PSA/ee/docs/plans/2025-11-06-managed-email-domain-orchestration-plan.md

Managed Email Domain Orchestration (EE) – Implementation Plan

Date: November 6, 2025
Authors: Codex (draft)
Status: Draft
Edition: Enterprise Only

1. Problem Statement

Alga PSA currently sends all outbound application mail from the platform’s shared Resend domain, even for hosted Enterprise tenants. Customers need to send transactional messages from their own domains without managing provider credentials or separate infrastructure. We must support tenant-managed sending domains while keeping the provider abstraction generic and future‑proof.

2. Overall Work Statement

Deliver an enterprise-only managed email domain orchestration system that lets hosted Alga PSA tenants verify and activate their own sending domains through guided DNS setup, Temporal-managed workflows, and provider-agnostic automation, ultimately enabling outbound mail to originate from tenant-branded domains without exposing provider-specific details.

3. Phased To-Do List

Phase 1 – Foundations (Services & Workflows)

1. ✅ Scaffold ee/server/src/services/email/ManagedDomainService.ts with createDomain, checkDnsAndProviderStatus, activateDomain, deleteDomain.
2. ✅ Add provider factory hook in ee/server/src/services/email/ManagedDomainService.ts that instantiates ResendEmailProvider via server/src/services/email/EmailProviderManager.ts utilities.
3. ✅ Create DNS lookup helper (ee/server/src/services/email/dnsLookup.ts) to query TXT/MX/CNAME records using dns.promises.
4. ✅ Register EE-only workflow actions by exporting the service through packages/product-email-domains/ee/entry.ts and wiring shared/workflow/init/registerWorkflowActions.ts.
5. ✅ Implement Temporal workflow file ee/temporal-workflows/src/workflows/managed-email-domain-workflow.ts with states/signals described in Section 7.
6. ✅ Add supporting activities in ee/temporal-workflows/src/activities/email-domain-activities.ts (provision, dnsCheck, activate, cleanup) and register them in ee/temporal-workflows/src/activities/index.ts.
7. ✅ Update ee/temporal-workflows/src/workflows/index.ts to export the new workflow and configure the worker task queue.
8. ✅ Extend ee/temporal-workflows/src/config/startupValidation.ts to require queue/env vars (EMAIL_DOMAIN_TASK_QUEUE, etc.).

Phase 2 – Application Surface (Server Actions & UI)

1. ✅ Add workflow client wrapper ee/server/src/lib/email-domains/workflowClient.ts (Temporal enqueue + signals).
2. ✅ Create EE server actions file ee/server/src/lib/actions/email-actions/managedDomainActions.ts exposing add/verify/delete operations.
3. ✅ Update packages/product-email-settings/ee/entry.tsx to point at a new EE component.
4. ✅ Build EE UI components:
   • ee/server/src/components/settings/email/ManagedEmailSettings.tsx (top-level tab content).
   • ee/server/src/components/settings/email/ManagedDomainList.tsx (status table).
   • ee/server/src/components/settings/email/DnsRecordInstructions.tsx (copyable DNS cards).
5. ✅ Modify server/src/components/settings/general/SettingsPage.tsx to load the EE package entry (ensure CE build untouched).
6. ✅ Update feature-flag usage or edition guards so only Enterprise tenants see the managed tab (done 2025-11-06 – outbound email UI now always renders the managed-domain card).

Phase 3 – Verification & Activation (Business Logic)

1. ✅ Implement DNS propagation checks in ManagedDomainService.checkDnsAndProviderStatus using the helper from Phase 1.
2. ✅ Extend shared/workflow/init/registerWorkflowActions.ts to call ManagedDomainService (via package import) for create/verify/activate actions.
3. Update ee/server/src/lib/services/TenantEmailService.ts to prioritize default_from_domain from verified managed domains when building the from header.
4. Persist analytics events (e.g., email_domain.verified) in ee/server/src/lib/analytics/posthog.ts.
5. Ensure tenant_email_settings.provider_configs gets a managed provider entry by default (update server/src/lib/actions/email-actions/emailSettingsActions.ts and EE override if needed).

4. Goals

• Allow Enterprise tenants to request, verify, and activate custom sending domains within the hosted environment.
• Hide vendor-specific terminology (Resend) from the tenant UI.
• Centralize provider automation in an EE-only “Managed Email Domain Service” that can work with Temporal workflows.
• Preserve pluggability so additional providers (e.g., SES, SendGrid) can be added later without UI or API churn.

Non-Goals

• Customer-managed SMTP credential onboarding (already handled today).
• Extending the feature to Community Edition.
• Immediate bounce/complaint webhook self-service (tracked separately).

5. High-Level Solution

1. Enterprise Domain Orchestration Service

   • New EE service (e.g., ee/server/src/services/email/ManagedDomainService.ts) wraps IEmailProvider domain lifecycle APIs (create, verify, delete).
   • Uses centralized credential management (Secrets) and provider configuration to instantiate the correct adapter (ResendEmailProvider initially).
   • Persists provider domain IDs, DNS instructions, and status updates in email_domains.

2. Temporal Workflow Integration

   • Create an EE workflow (ee/temporal-workflows/src/workflows/email-domain-verification-workflow.ts) managed by the existing temporal worker.
   • Activities interact with the Managed Domain Service to:
     • Create provider-side domain records and capture DNS requirements.
     • Deliver DNS record instructions to the domain owner and monitor for propagation.
     • Poll verification status / trigger verification runs.
     • Activate domains post-verification (update tenant email settings, set default from domain).
   • Signals/events mirror the portal domain workflow (e.g., user triggers verification, DNS configured, etc.).

3. Workflow Client + Actions

   • Add EE workflow client utilities (ee/server/src/lib/email-domains/workflowClient.ts) similar to custom portal domains.
   • Replace mock actions in shared/workflow/init/registerWorkflowActions.ts by wiring through EE package exports:
     • createManagedDomain → Managed Domain Service createDomain.
     • triggerManagedDomainVerification → fetch status via Temporal activity.
     • activateManagedDomain → persist as tenant default domain.

4. UI / Server Actions

   • Introduce EE-only email settings component via package alias (packages/product-email-settings/{oss,ee}/entry.tsx).
   • EE version removes direct API key inputs, surfaces DNS instructions, verification progress, and Temporal-triggered statuses.
   • Server actions (ee/server/src/lib/actions/email-actions/managedDomainActions.ts) call workflow client and Managed Domain Service.
   • CE retains existing manual flows through OSS package exports.

5. Tenant Email Sending

   • Adjust EE override of TenantEmailService to prioritize verified tenant domain for from headers and to initialize the managed provider when available.
   • Preserve fallback to platform default when no verified domain exists.

6. Architecture Overview

Tenant UI (Email Settings - EE package)
    │
    ├── EE server actions (managedDomainActions.ts)
    │       │
    │       ├── Workflow Client → Temporal Workflow
    │       │        ├── Activities → Managed Domain Service → Provider Adapter (Resend)
    │       │        └── DB updates via shared models
    │       └── Direct Managed Domain Service calls (e.g., read status)
    │
    └── tenant_email_settings / email_domains tables
             │
             └── TenantEmailService (EE override) selects verified domain for outbound mail

7. Temporal Workflow Design

• Workflow Name: managedEmailDomainWorkflow
• Queue: reuse temporal worker (e.g., email-domain-workflows task queue).
• Inputs: { tenantId, domainName, trigger } (trigger = register, refresh, delete).
• States: created, awaiting_dns, verifying, verified, failed, deactivated.
• Signals:
  • dnsConfigured – domain owner confirms DNS records were created.
  • refreshStatus – admin requests immediate re-check.
• Activities:
  1. provisionProviderDomain – call Managed Domain Service createDomain, store provider IDs and DNS instructions, surface instructions to the tenant (UI + email).
  2. checkDnsAndVerificationStatus – verify DNS propagation (e.g., public TXT/MX/CNAME lookup) and poll provider status; update DB and determine next step.
  3. activateTenantDomain – mark domain verified, update tenant_email_settings.default_from_domain, push analytics event.
  4. cleanupProviderDomain (future) – delete domain if tenant removes it.
• Retries/Error Handling:
  • Exponential backoff for provider API rate limits.
  • Max runtime guard (e.g., 7 days) before failing workflow and surfacing instructions to support.

8. Data & Persistence

• Reuse existing email_domains columns (provider_id, provider_domain_id, dns_records, status, failure_reason).
• Add structured metadata (JSON) for Temporal workflow execution ID and audit trail.
• Ensure tenant_email_settings.provider_configs includes a managed provider config template (no per-tenant API key).
• Set default_from_domain to verified domain when activation completes; store previous domain for rollback.

9. UI/UX Updates (EE)

• Tabs in Email Settings:
  • “Managed Sending” (EE): wizard to add domain, display DNS records, track status.
  • “Other Providers” (legacy): optional view for SMTP credentials.
• Show DNS records grouped by type with copy-to-clipboard; emphasize that verification may take time.
• Expose workflow status messages (e.g., “Waiting for DNS”, “Verification in progress”).
• Provide manual “Retry verification” button that triggers refreshStatus signal.
• Remind domain owners about required DNS updates with contextual help, links to registrar guides, and status badges that indicate whether DNS records are detected yet.

10. Work Breakdown

1. Planning/Infra
   • Finalize workflow name/queue configuration and secrets usage.
   • Define naming convention for generated sender addresses (e.g., notifications@{tenantDomain}).
2. Backend Foundations
   • Implement Managed Domain Service with provider factory.
   • Wire up Temporal workflow and activities within the existing worker harness.
   • Update workflow action registry via EE package export.
3. Server Actions & APIs
   • Add EE actions for create/verify/delete domain; update GraphQL/REST endpoints if applicable.
   • Ensure CE stubs return current behavior.
4. UI Layer
   • Build EE Email Settings component; update package alias resolution and feature flag gating.
   • Adjust CE UI to hide managed-domain features.
   • Add analytics events for domain lifecycle milestones.

11. Risks & Mitigations

• Provider API Limits: Add retry/backoff strategy, monitor via logs.
• DNS Verification Delays: Provide clear instructions, surface TTL expectations, allow manual retries.
• Temporal Worker Load: Reuse existing worker but ensure queue isolation and metric dashboards.
• Multi-Provider Future: Keep service provider-agnostic, encapsulate provider selection logic.
• Tenant Misconfiguration: Validate domain format, restrict apex records, provide warnings before activation.

12. Open Questions

• Do we allow tenants to rename the default sender mailbox per domain?
• Should we automatically notify support when a domain stalls in verification beyond N hours?
• How do we handle domain deletion if messages are in-flight (grace period vs. immediate removal)?

13. Next Steps

1. Engineering sign-off on workflow + service design.
2. Break out Phase 1 tasks into individual tickets with resource assignments.
3. Align UI/UX specifications for the managed email settings components before Phase 2 begins.