Skip to content
Pidgely Docs

API reference · Native API (v1)

Create a domain

POSThttps://api.pidgely.com/v1/domains
View as Markdown

Adds a sending domain and returns it with the DNS records to publish.

Authorization: Bearer pdg_…. An API key with the full scope.

Body parameters

JSON object.

Name Type Required Description
name string Yes Display name.
region string No Informative; set by the platform.
custom_return_path string No Bounce subdomain label (default bounces).
tls string No opportunistic (default): TLS when the receiving server offers it. enforced: deliver only over TLS. One of opportunistic, enforced.
open_tracking boolean No Accepted, not supported yet (always false).
click_tracking boolean No Accepted, not supported yet.
capabilities object No —
capabilities.sending string No —
capabilities.receiving string No enabled is rejected (receiving not supported yet).

Request

cURL
curl -X POST 'https://api.pidgely.com/v1/domains' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "acme.com"
}'

Response

201 Created with a JSON object.

Errors

Native routes return {"error": {"code", "message", "field", "request_id"}}. See Errors.

Status Code When
401 missing_api_key No Authorization: Bearer header.
403 invalid_api_key, insufficient_scope The key is invalid or lacks the scope.
404 not_found The resource does not exist in this account.
422 validation_error A field is missing or invalid; field names it.
429 rate_limited, daily_quota_exceeded Too many requests, or the quota is used up.