:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Domain Connect
Automates DNS configuration for PostHog features that require users to add DNS records (email sending, managed reverse proxy). Instead of manually copy-pasting records at their DNS provider, users click a button and get redirected to approve pre-filled records.
Uses the Domain Connect synchronous flow with request signing.
How it works
User clicks "Configure automatically"
│
▼
Frontend calls POST /api/environments/:id/integrations/domain-connect/apply-url
│
▼
Backend resolves context (email/proxy) → domain, template variables, service ID
│
▼
Backend builds signed apply URL → returns to frontend
│
▼
Frontend opens URL in new tab → DNS provider shows pre-filled records
│
▼
User approves → provider redirects back to PostHog with ?domain_connect=<context>
│
▼
Frontend detects redirect param, cleans URL, parent component re-verifies
Two paths for provider detection:
- Auto-detection: DNS TXT lookup on
_domainconnect.{domain}reveals the provider. The banner shows "Your DNS is managed by {provider}" with a single button. - Manual selection: Auto-detection fails, but we show "I use {provider}" buttons for each provider in our allowlist. The user picks theirs.
Architecture
Backend (posthog/domain_connect.py)
Single module with all Domain Connect logic:
- Discovery:
discover_domain_connect()— DNS TXT lookup + provider settings fetch, cached 1 hour - URL building:
build_sync_apply_url()— constructs the redirect URL - Signing:
sign_query_string()— RSA-SHA256 signs the query string (required by Cloudflare) - Domain parsing:
extract_root_domain_and_host()— splits FQDNs handling multi-part TLDs - Context resolvers:
resolve_email_context()/resolve_proxy_context()— extract template variables from the relevant PostHog resource. Both return aDomainConnectContext, which also carries the root domain that discovery runs against and the host that scopes the records to a subdomain. - Provider allowlist:
DOMAIN_CONNECT_PROVIDERSdict — empty until providers accept our templates
API endpoints (posthog/api/integration.py)
Two endpoints on IntegrationViewSet:
GET domain-connect/check?domain=— checks if a domain's DNS provider supports Domain ConnectPOST domain-connect/apply-url— generates a signed apply URL for a given context (emailorproxy)
Frontend (this directory)
domainConnectLogic.ts— Kea logic keyed by instance. Handles discovery check, URL generation, and redirect detection. All API interaction lives here.DomainConnectBanner.tsx— Drop-in banner component. Renders one of three states: auto-detected provider, manual provider buttons, or nothing.assets/— Local provider logos (Cloudflare, Vercel).templates/— Backup copies of the Domain Connect template JSON files (see below).
Settings
Two env vars in posthog/settings/web.py:
DOMAIN_CONNECT_PRIVATE_KEY— PEM-encoded RSA private key for signing apply URLsDOMAIN_CONNECT_KEY_ID— Key identifier published via DNS (default:_dcpubkeyv1)
Usage
Drop DomainConnectBanner anywhere DNS records need to be configured:
<DomainConnectBanner
logicKey={`email-${integration.id}`}
domain="example.com"
context="email"
integrationId={integration.id}
/>
<DomainConnectBanner
logicKey={`proxy-${record.id}`}
domain={record.domain}
context="proxy"
proxyRecordId={record.id}
/>
Each instance gets its own keyed logic — no state sharing between banners.
Adding a new context
To use Domain Connect for a new feature:
- Create a template JSON in
templates/and submit it to Domain-Connect/Templates. - Add a
resolve_<context>_context()function inposthog/domain_connect.pyreturning(domain, service_id, variables). - Add the context branch in the
domain_connect_apply_urlendpoint inposthog/api/integration.py. - Add the context value to the
contextprop type indomainConnectLogic.ts. - Mount
<DomainConnectBanner>with the new context in your UI.
Adding a new DNS provider
- Submit our templates to Domain-Connect/Templates.
- Contact the provider to register the templates in their store.
- Once confirmed, add their
_domainconnectTXT endpoint toDOMAIN_CONNECT_PROVIDERSinposthog/domain_connect.py. - Add the provider name to
DomainConnectProviderNameinfrontend/src/queries/schema/schema-general.tsand runhogli build:schema. - Add their logo SVG to
assets/and register it inPROVIDER_LOGOSinDomainConnectBanner.tsx.
Templates
The templates/ directory contains backup copies of the JSON files submitted to
Domain-Connect/Templates. DNS providers
pull from that external repo — they do not read these files. We keep them here so the
canonical definitions live alongside the code.
| File | Purpose |
|---|---|
posthog.com.email-verification-us.json |
Email DNS records (US) |
posthog.com.email-verification-eu.json |
Email DNS records (EU) |
posthog.com.reverse-proxy-us.json |
Proxy CNAME (US) |
posthog.com.reverse-proxy-eu.json |
Proxy CNAME (EU) |
Tests
Backend tests live at posthog/test/test_domain_connect.py (25 tests covering domain
parsing, region mapping, URL building, signing, discovery, and provider listing).