Branded Domains
Add and verify your own short-link domain - /v1/domains.
Use your own domain (e.g. go.yourbrand.com) instead of go.esmsafrica.io. Branded domains are available on Business plans and above.
Add a domain
POST https://links.esmsafrica.io/v1/domainsRequest body
{ "hostname": "go.yourbrand.com" }Response - 201
{
"id": "d1a2…",
"hostname": "go.yourbrand.com",
"verified": false,
"tls_ready": false,
"verify_token": "f3a9c1…",
"txt_record": "_esms-links.go.yourbrand.com TXT f3a9c1…",
"created_at": "2026-08-03T09:00:00Z"
}Add the txt_record at your DNS provider, then call verify.
Errors
| Status | Description |
|---|---|
402 | Paid plan required, or your plan's domain limit is reached |
403 | Branded domains not available on your plan |
409 | Hostname already verified by another account, or you already added it |
422 | Invalid hostname |
Adding a hostname does not reserve it. Until you verify the TXT record, anyone else may add the same hostname with their own token; whoever proves DNS control first gets it and the other pending claims are released. An unverified claim is removed after 72 hours (claim_expires_at).
Verify a domain
POST https://links.esmsafrica.io/v1/domains/{id}/verifyChecks that the TXT record _esms-links.<hostname> matches your verify_token. On success verified becomes true and status is verified; we then provision a TLS certificate for the host and tls_ready becomes true once it is live. Returns the domain object.
Keep the TXT record in place. Verified domains are re-checked every day; if the record is missing on two checks in a row the domain's status becomes lost (lost_at is set). Its links keep working, but another account that proves control of the DNS can then take the hostname over. Put the record back and the next check clears the flag.
| Status | Description |
|---|---|
400 | TXT record not found yet - add it and allow DNS to propagate |
404 | The domain isn't yours or doesn't exist |
List domains
GET https://links.esmsafrica.io/v1/domainsReturns your domains, each including the txt_record while still pending.
Delete a domain
DELETE https://links.esmsafrica.io/v1/domains/{id}Returns 204 No Content. Short links created on the domain are not deleted: they are detached from it and fall back to the shared go.esmsafrica.io host. Delete or repoint those links first if you don't want them served there.
Once a domain is verified, pass its id as domain_id when creating a link to mint short links on that host.