Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Domains

Every domains endpoint, generated from the API's own schemas.

List domains

get/api/v1/domains

Parameters

  • limitnumber
  • cursorstring

Responses

  • 200A page of domains.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Connect a domain

post/api/v1/domains

Returns the domain **and the records to publish**, because showing them to your own customer is the one thing every caller does next. DNS is the step this API cannot perform — we cannot write in somebody else’s zone — so the job is to make the human step delegable. Watch `dns_complete`: it is false while the DKIM records do not exist yet, and a list published in that state verifies and cannot sign mail.

Parameters

  • Idempotency-Keystring

    Any string unique to this attempt, reused on its retries. A repeat with the same key and the same request returns the first answer with `Idempotent-Replay: true` and does nothing — no second email. The same key with a different request is a `409`. Kept for 24 hours; a failure is not kept, so a retry after one runs.

Body

  • domainstringrequired

    A domain name you own, or the shared one. An alternative to `domain_id`.

  • inbound_enabledboolean

Responses

  • 201The domain and its records.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 402Your plan does not include this. `error.message` says what does.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409This `Idempotency-Key` was used with a different request, or that request is still running. Nothing was sent by this call.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Fetch one domain, with the state of each record

get/api/v1/domains/{id}

`dns_records[].status` says which of ownership, MX, SPF, DKIM and DMARC is missing or wrong, and `found` says what is there instead — which is the difference between your support queue and your customer fixing one TXT record.

Parameters

  • idstringrequired

Responses

  • 200The domain.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains/{id} \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Turn the catch-all on or off

patch/api/v1/domains/{id}

The one thing about a domain that can change. Catch-all is two gates: this switch, and a `catch_all` routing rule saying where the mail goes — so turning it on without a rule does nothing, and turning it off later does not throw away where the mail was going.

Parameters

  • idstringrequired

Body

  • catch_all_enabledbooleanrequired

Responses

  • 200The domain.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains/{id} \
  -X PATCH \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Disconnect a domain

delete/api/v1/domains/{id}

Takes its addresses, their mail, their routing rules and their webhooks with it. There is no undo.

Parameters

  • idstringrequired

Responses

  • 200Deleted.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains/{id} \
  -X DELETE \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

The records as a zone file

get/api/v1/domains/{id}/zone-file

BIND format, which Route 53, Cloudflare and most registrars import and our JSON is not. TTLs are 300: these records change twice, and a long TTL on one you are getting right is an hour of somebody else’s cache.

Parameters

  • idstringrequired

Responses

  • 200A zone file.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains/{id}/zone-file \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

One-click DNS setup, when the provider supports it

get/api/v1/domains/{id}/setup-link

The **Domain Connect** standard: the URL returned is signed by and points at the domain’s own DNS provider, where the owner signs in, reviews the records and approves — the provider writes them. Nothing here is a credential of ours. Answers `200` either way. `supported: false` is a fact about somebody else’s DNS provider rather than a failure of this request, and `reason` says whose problem it is: `provider` means that zone cannot do it, `unconfigured` means this deployment is not registered. Either way, fall back to `GET /domains/{id}/zone-file` or the `records` on the domain. `template` is `mail` (everything: ownership, DKIM and MX) or `mx` (the MX alone, for a domain already sending through us that is now going to receive).

Parameters

  • idstringrequired
  • templateenum

    Which records the link should publish.

    mail · mx

Responses

  • 200Whether it can be done, and where.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains/{id}/setup-link \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Check the zone again

post/api/v1/domains/{id}/verify

Idempotent and safe to poll — calling it on a verified domain re-checks and says so rather than erroring. Both halves in one answer: ownership, and whether mail is configured. The floor on how often this is worth calling is the zone’s TTL. Better still, subscribe to `domain.verified` and do not poll.

Parameters

  • idstringrequired

Responses

  • 200Where it stands.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/domains/{id}/verify \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json