Create Domain

Create a Leadpush-managed sending domain for your workspace. The response includes the DNS records to add at your DNS provider, with is_valid values included for each record.

Creation Behavior

What happens when a domain is created

  • Developer-created domains always use the Leadpush provider.
  • Do not send provider; provider input is rejected.
  • dkim_selectors can be used to request custom DKIM selectors. Each selector must be 10 characters or fewer.
  • tracking_mode requires tracking_subdomain and currently accepts direct or cloudflare.
  • The endpoint requires the domains.enabled entitlement and enforces the account domains.max limit when configured.
POST
/v1/domains

Create a Leadpush sending domain

Request body

namestring Required

Domain name to add, such as `example.test`

dkim_selectorsarray

Optional list of DKIM selectors. Each selector must be 10 characters or fewer.

tracking_subdomainstring

Optional single DNS label to use for click tracking, such as `click`

tracking_modestring

Optional tracking mode. Accepted values are `direct` and `cloudflare`.

Create Domain
curl -X POST https://api.leadpush.io/v1/domains \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "name": "example.test",
  "dkim_selectors": ["default"],
  "tracking_subdomain": "click",
  "tracking_mode": "cloudflare"
}'
Response Example
{
"data": {
  "uuid": "<domain_uuid>",
  "name": "example.test",
  "domain": "example.test",
  "verified": false,
  "provider": "leadpush",
  "status": "pending",
  "verification": "pending",
  "mail_from_domain": "bounces.example.test",
  "mail_from_verified": false,
  "dns": [
    {
      "type": "CNAME",
      "name": "default._domainkey.example.test",
      "value": "default._domainkey.smtp-domain-1.leadpush.net.",
      "is_valid": false
    },
    {
      "type": "MX",
      "name": "bounces.example.test",
      "value": "10 bounces.leadpush.net",
      "is_valid": false
    }
  ],
  "updated_at": "2021-01-01T00:00:00.000Z",
  "created_at": "2021-01-01T00:00:00.000Z"
}
}

Errors

Common create failures

  • The endpoint returns 403 with error: "upgrade_needed" when the workspace owner does not have domains.enabled.
  • The endpoint returns 403 with error: "limit_exceeded" when creating the domain would exceed domains.max.
  • The endpoint returns 422 when the domain input is invalid or provider is included.