Self-hosting

Changing your domain

Move a Notifuse instance to a new address, and open the console on workspace custom domains.

Notifuse knows its public address through API_ENDPOINT, set as an environment variable or saved by the Setup Wizard; the environment variable wins when both exist. The console sends every request to that address, and it is written into emails, invitations, webhooks registered with your email providers and the SSO redirect URI. Moving an instance to a new domain means changing API_ENDPOINT, then updating the places that copied it.

Warning

Keep the old domain pointing at Notifuse, or redirecting to the new one with the path and query string intact, for as long as people may open emails you have already sent. Their tracking, unsubscribe, notification center and web version links carry the old address, and nothing can update an email that has been delivered.

Switching to the new domain

  1. Route the new domain to Notifuse in your reverse proxy, with a TLS certificate, and keep the old domain routed as well.
  2. Change API_ENDPOINT:
    • Set as an environment variable: change it and restart Notifuse.
    • Saved by the Setup Wizard: sign in as root on the old domain, open System Settings (the button above the workspace list), change API Endpoint and save. Saving restarts Notifuse: the process exits and your container or service manager starts it again, which the provided Docker Compose file does with restart: unless-stopped. The field is disabled when the environment variable is set, since the environment variable would override it.
  3. Sign in again on the new domain. Sessions are kept per address, so a session opened on the old domain does not carry over.
  4. Work through the list below.

Note

Locked out after the move? If the old domain no longer reaches Notifuse, the console on the new domain cannot reach its API either, and the sign-in page says which address it tried. Set API_ENDPOINT to the new address as an environment variable and restart: it takes precedence over the value the Setup Wizard saved.

What else uses the address

Uses the addressAfter the changeWhat to do
Links in emails already sent: click tracking, open tracking, unsubscribe, List-Unsubscribe, notification center, web versionKeep pointing at the old domainKeep the old domain routed to Notifuse. Workspaces with a Custom Endpoint URL use that domain instead and are not affected. If you redirect the old domain to the new one instead, unsubscribe and notification center links that click tracking wrapped in emails sent before 42.2 show a confirmation page first: one extra click. When a workspace changes its own custom domain, redirect the old one to API_ENDPOINT rather than to the new custom domain: a web version opens only on the domain it was sent with and on API_ENDPOINT.
Pending workspace invitationsLink to the old domainKeep the old domain routed, or resend the invitations: a resent invitation uses the new address.
Email provider webhooksRegistered once, with the address of the timeFor each integration, open Settings → Integrations and choose Re-register webhooks in its ⋯ menu. See Email provider webhooks.
WEBHOOK_ENDPOINTOverrides API_ENDPOINT for webhooks when setChange it too, then re-register.
Single sign-onThe redirect URI is derived from API_ENDPOINT unless OIDC_REDIRECT_URI is setAdd https://<new-domain>/api/user.oidc.callback at your identity provider, and update OIDC_REDIRECT_URI if you set it. See Single Sign-On.
URLs copied into other tools: Supabase auth hooks, the Zapier connection, applications calling the APIStill call the old domainUpdate them with the new address.
The web analytics snippet installed on your sitesIts endpoint and its script URL name the old domain, unless the workspace has a Custom Endpoint URLInstall the updated snippet, or keep the old domain routed.
Workspace Custom Endpoint URLsTheir DNS check expects a CNAME to the API_ENDPOINT host, and runs only when a custom domain is set or changedExisting custom domains keep working while their CNAME target still reaches Notifuse. Point them at the new host when convenient.
CORS_ALLOW_ORIGINLists the origins allowed to call the API, when setAdd the new origin. See Workspace custom domains.

Email provider webhooks

Notifuse registers its webhook with your email provider when you create the integration, using the address at that time, and never updates it on its own. Re-register webhooks sends the new address:

  • Mailgun and SendGrid replace the old address.
  • Postmark, SparkPost, Mailjet and Amazon SES add the new address next to the old one. Delete the old webhook in the provider’s dashboard, or for Amazon SES the old SNS subscription, so events are not delivered twice.

An integration can show as registered while its webhook still points at the old domain. Hover over the webhooks status of an integration in Settings → Integrations to see the address each endpoint uses.

Amazon SES confirms the new SNS subscription automatically, which only succeeds once AWS can reach Notifuse on the new domain.

Opening the console on a workspace custom domain

A workspace’s Custom Endpoint URL also serves the console: if a workspace uses https://news.example.com, its members can sign in at https://news.example.com/console. The console and notification center opened there send their requests to API_ENDPOINT, from the custom domain’s origin.

  • With the default CORS_ALLOW_ORIGIN (*) there is nothing to configure.
  • If you restrict CORS_ALLOW_ORIGIN, list every workspace custom domain, separated by commas: CORS_ALLOW_ORIGIN=https://news.example.com,https://mail.other-brand.com. A domain left out cannot sign in to the console, and its notification center cannot load preferences.
  • Sessions are kept per address: signing in on a custom domain does not sign you in on the main domain, and the other way round.
  • Single sign-on and invitation links finish on the API_ENDPOINT address, not on the custom domain.