Custom domain setup

Connect a branded short domain, publish the required DNS records, and verify it step by step.

Prerequisites

Before starting, ensure you have:

A registered domain name you control, with access to its DNS settings at your registrar or DNS provider (such as Cloudflare, Route53, GoDaddy, Namecheap, or similar).
Organization owner or admin privileges in Nimriz.
Decided which exact hostname you want to use (e.g., links.yourbrand.com). Nimriz matches hostnames strictly-plan your choice before creating campaigns, because changing it later means updating all previously shared links.

Step 1-Add the custom domain

In your Nimriz dashboard, go to Settings → Domains.
Click Add custom domain.
Enter your hostname exactly as you want it to appear in short links, for example links.example.com. Do not include https:// or a trailing slash.
Click Save. The domain is added with a status of Pending.

Step 2-Publish the verification TXT record

Nimriz generates a unique TXT record to prove you control the domain. This record is visible in your domain settings immediately after adding the domain.

Copy the Name and Value shown in your Nimriz dashboard for the TXT record. They will look similar to:
```
Type:  TXT
Name:  _nimriz-verify.links.example.com
Value: nimriz-verify=abc123def456...
```
Log in to your DNS provider.
Create a new TXT record with the exact name and value from Nimriz. Do not alter the values in any way-even a trailing space will cause verification to fail.
Save the record.

Provider-specific notes:

Cloudflare: Set the record's Proxy status to DNS only (grey cloud), not proxied. Proxying TXT records can break verification.
GoDaddy / Namecheap: Some providers strip the root domain from the hostname field automatically. If your domain is example.com, you may only need to enter _nimriz-verify.links instead of the full _nimriz-verify.links.example.com. Check your provider's documentation if unsure.
AWS Route 53: Enter the full subdomain in the Name field including a trailing dot if required by the interface (e.g., _nimriz-verify.links.example.com.).

Step 3-Publish the CNAME record for traffic routing

In addition to the verification TXT record, you must add a CNAME record that points your hostname at the Nimriz edge network. This is what makes visitors' browsers actually reach Nimriz when they follow one of your short links.

The required CNAME target is shown in your dashboard after adding the domain. It will look similar to:

Type:   CNAME
Name:   links.example.com   (or just "links" for subdomain setups)
Target: cname.nimriz.com

Publish this record at your DNS provider alongside the TXT record. Both records are required-the TXT for ownership verification, and the CNAME for traffic.

Step 4-Trigger verification

Return to Settings → Domains in your Nimriz dashboard.
Find your domain and click Verify now (or the equivalent check button).
Nimriz will attempt to confirm the TXT record is visible in DNS.

DNS propagation time: Changes to DNS records are not instant-they can take anywhere from a few minutes to a few hours to become globally visible, depending on your provider and the TTL (Time to Live) setting on your DNS records. If verification fails on the first attempt, wait 15–30 minutes and try again.

Step 5-Wait for Ready status

After DNS verification succeeds, Nimriz activates the custom hostname on the Cloudflare edge and issues an SSL certificate. The domain moves from Verified to Ready once this activation is complete.

This typically takes a few minutes after verification. You do not need to do anything-the dashboard will update automatically.

Your domain is live for link creation and redirects only once it reaches Ready status. The distinction matters: a domain can be verified (ownership confirmed) but not yet ready (edge not yet activated). Links created on a domain that is not Ready will not redirect correctly until activation completes.

Testing your domain

Once your domain shows Ready:

Create a test link using your custom domain and a recognizable slug (e.g., links.example.com/test-link).
Open the short link in a browser (or use curl -I https://links.example.com/test-link).
Confirm you are redirected to the destination URL.
Confirm the SSL padlock is present-Nimriz provisions SSL automatically for custom domains.

If the link does not redirect, check:

The domain status in your dashboard (must be Ready, not just Verified).
Whether the CNAME record is fully propagated (use a tool like dnschecker.org to check from multiple locations).
Whether your link is active and not expired or disabled.

Domain constraints

Strict host matching: links.example.com and www.links.example.com are treated as separate domains. Add each hostname you intend to use.
One canonical hostname per campaign: Decide upfront whether to use an apex domain (example.com) or a subdomain (links.example.com). Mixing them requires managing two separate domain records.
Deep links: Deep link support (routing mobile visitors into your iOS or Android app) requires a verified, traffic-ready custom domain that is exclusive to one account. See Routing rules and preview for details.
API access: Custom domains default to private API access, meaning all link-management API calls require a valid workspace API key.

Troubleshooting

Verification is stuck in Pending after several hours

Confirm the TXT record is published on the correct hostname. The most common mistake is publishing it on the root domain (example.com) instead of the subdomain (links.example.com).
Use a DNS lookup tool (dig TXT _nimriz-verify.links.example.com or an online checker) to confirm the record is visible from outside your network.
Ensure there are no conflicting TXT records on the same hostname with an identical or overlapping name.

SSL certificate is not being issued

Confirm the CNAME record is active and pointing to the correct Nimriz edge target.
Cloudflare Universal SSL requires the CNAME to be properly propagated before it can issue a certificate.
If the domain was previously used on another service, remove any A records, old CNAME records, or CAA records that may conflict.

My domain went from Ready back to a non-Ready state

This can happen if DNS records are removed or modified after initial setup, or if a domain's Cloudflare edge activation expires. Re-check your CNAME record and trigger a re-verification from the dashboard.