eSMS AfricaeSMS Africa
API ReferenceLinks API

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/domains

Request 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

StatusDescription
402Paid plan required, or your plan's domain limit is reached
403Branded domains not available on your plan
409Hostname already verified by another account, or you already added it
422Invalid 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}/verify

Checks 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.

StatusDescription
400TXT record not found yet - add it and allow DNS to propagate
404The domain isn't yours or doesn't exist

List domains

GET https://links.esmsafrica.io/v1/domains

Returns 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.

On this page