---
title: "Start guided DNS setup"
method: POST
path: "/api/domains/{id}/dodomain-session"
tags: ["Domains"]
---

# Start guided DNS setup

`POST /api/domains/{id}/dodomain-session`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/domains/{id}/dodomain-session`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `domains:write`)

Mint a short-lived guided-setup session for this domain and return the URL that opens it. The URL is the whole point: DNS records have to be published at the domain's registrar, which is a place only a person with those credentials can reach — so this call cannot finish the job, it hands it over.

The session is bound to this one domain, expires on its own, and returns the browser to the Sendly domains settings page when it is done. Verification authority stays with SES either way: guided setup publishes the records, it does not decide whether they are correct.

`503 DODOMAIN_NOT_CONFIGURED` when the deployment has no guided-setup provider. `429 DODOMAIN_SESSION_COOLDOWN` for a second call within 60s on the same domain — each session is metered, so a double submit is refused rather than charged twice.

Requires the `domains:write` scope — Add and remove sending domains, and trigger verification.

## Path parameters

- `id` string, uuid, required

## Response `200`

Guided setup session

- object
  - `data` object, required
    - `connectUrl` string, uri, required: Open this in a browser to publish the records. Short-lived and domain-specific.
    - `expiresAt` string, required: When `connectUrl` stops working.
    - `token` string, required
  - `success` true, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized — missing or invalid auth
- `403`: Forbidden — insufficient permissions or project disabled
- `404`: Resource not found
- `429`: Rate limit or billing limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/sendly/apis/sendly-api.md) · [All operations](https://skmtc.dev/sendly/apis/sendly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sendly/apis/sendly-api/revisions/ce7cfb7f7c7e?raw)