Skip to main content

​
Connect a custom domain for short links

By default Orbit mints short links on https://api.orbit.devotel.io. A branded host such as https://go.yourbrand.com puts your own domain in front of every recipient instead. This guide walks the full setup: DNS, TLS, a redirect check, the tenant setting, and a test mint. The long-form behaviour reference (resolution order, click analytics, failure modes) lives in Short links with click tracking, §4. This page is the setup checklist.

​
1. When to use a branded domain

Recipients tap a link that carries your brand instead of a platform host. If your email already authenticates as yourbrand.com (DKIM, Return-Path), a go.yourbrand.com short link keeps the domain story coherent across channels, and recipient trust follows coherence: the same brand in the message and in the link. Set one when you send tracked links at volume and you control the domain’s DNS. Stay on the platform default when you only mint the occasional link; the default needs no setup and resolves everywhere.

​
2. Pick a host shape

The setting accepts a bare https:// host only, for example https://go.yourbrand.com. The save-time validation and the server that mints links enforce the same rule:
  • https:// required in production (http:// is accepted for staging vanity hosts only).
  • No path, query, or fragment: https://go.yourbrand.com, not https://go.yourbrand.com/landing. Orbit appends /l/:code itself.
  • A trailing slash is stripped silently on save.
Use a subdomain you own and can delegate; go., link., and t. are common choices. The apex is not required.

​
3. Provision DNS

Add one CNAME record at your DNS provider: api.orbit.devotel.io is Orbit’s redirector: it serves the public GET /l/:code route your short links resolve through. If your onboarding contact handed you a dedicated redirector host, use that value instead. Wait out the record’s TTL before moving on. A CNAME that has not propagated reads as a missing host in every later step.

​
4. TLS

Recipients fetch short links over HTTPS only, so the host needs a valid certificate before any link mints on it. Orbit provisions the managed certificate for your host once the CNAME resolves, and your ops contact confirms issuance. Until then, requests to your host fail at the TLS handshake, which is exactly what the next step distinguishes from a routing problem. Keep the CNAME in place after issuance. A record removed mid-provisioning is the usual cause of a stalled certificate.

​
5. Verify the redirect path

Probe the route with a code that does not exist:
The healthy answer is an HTTP 404 with Orbit’s JSON error body, not a DNS failure or a TLS handshake error. The 404 proves DNS resolves, the certificate is valid, and the /l/:code route answers on your host. A real code returns a 3xx redirect whose Location header points at the target URL; curl -sSL follows it to your landing page.

​
6. Set the tenant field

Open Settings → General and find the Branded short-link domain card. Paste the bare host (https://go.yourbrand.com) and Save. The card validates before writing and shows one of these inline messages when a value cannot be saved:
  • Enter a full URL with a scheme, e.g. https://go.acme.li. when the scheme is missing or unparsable.
  • Must start with https:// (http:// is allowed for staging vanity domains only).
  • URL must include a host.
  • Use a bare host with no path, query, or fragment (e.g. https://go.acme.li). when the value carries a path, query, or fragment.
  • Domain is too long (max 256 characters).
On success the card shows a Short links use: badge with your host. Reset to default clears the value, with a confirmation, and returns future mints to the platform host. Saving a blank field clears it too.
The 201 Created response carries short_url. Confirm its host is your domain:
Then follow it on your host:
Expect a 3xx with Location: https://www.yourbrand.com/landing. Every mint path honors the setting from the moment it is saved: one-off API mints, the compose dialog’s shorten preview, and auto-shortened sends. Links minted before the change keep resolving on their original host. An invalid saved value never blocks a send. Minting falls back to https://api.orbit.devotel.io and writes a warn-level log line against the setting, so the misconfiguration is findable in your log trail. If links mint on the platform host despite a saved value, the stored host almost certainly carries a path or fragment; re-open the card, correct the value, save, and re-mint. Existing short URLs keep resolving either way.