Change the public URL

What the public URL is

The public URL is the HTTPS origin of the Convex HTTP site, CONVEX_PUBLIC_SITE_URL. Amazon SNS delivers SES events to /ses/events and inbound mail notifications to /ses/inbound there, and open and click tracking and unsubscribe links point at it. During setup the wizard checks that it reaches this installation and then keeps it fixed once AWS resources exist.

To move to a new one, for example from a local tunnel used during setup to a permanent host, use the Change action. Only the installation administrator can do this.

Before you start

1. Serve the new URL. The reverse proxy must forward it to the Convex HTTP site (convex:3211) with TLS in place, and it must be reachable from the internet. See reverse proxy and TLS.
2. Wait for any running region, inbound or domain operation to finish. The change is refused while one is in progress.

Change it

1. Open Amazon SES from the profile menu (the page at /instance/ses).
2. In the Delivery updates card, click Change.
3. In the Change public URL dialog, enter the New public URL and click Change URL.

The URL must be https:// with no port, path or query. Opensend first checks it the same way the wizard's connection check does: the new URL has to answer a fresh challenge with this deployment's proof. If the check fails, nothing changes and the dialog shows the reason.

When the check passes:

1. The URL is saved. Every region provisioned before runs its setup again, which subscribes the new URL to the region's event topic and, where receiving is set up, to its inbound topic. The Sending regions card shows each region's delivery updates as pending, and sending in that region pauses, until Amazon SNS confirms the new subscription, exactly as during first-time setup.
2. Once every region has finished, every domain refreshes so that its Tracking record points at the new host. A domain with a tracking subdomain shows that CNAME as pending until you update it at your DNS provider.
3. New emails use the new callback origin for fallback tracking and one-click unsubscribe. Preference-page links still use SITE_URL; verified custom tracking hosts keep their own hostname. Links in emails already sent keep their original host, so keep the old routes available if those links must continue to work.

Clean up in AWS

Opensend's IAM policy grants no sns:Unsubscribe, so the previous URL's subscriptions stay in Amazon SNS. Remove obsolete subscriptions in the SNS console after checking the new subscriptions. If the old endpoint becomes unreachable, SNS keeps retrying deliveries to it.

Update the environment

The dialog changes the URL Opensend gives to AWS and puts in emails. It does not edit .env.docker. If the new URL is also the origin your proxy serves for Convex HTTP actions, set CONVEX_PUBLIC_SITE_URL there to the same value and run pnpm setup again so the backend advertises it; setup preserves existing secrets.