API reference

Attach domain to providers

Registers a sending domain with one or more email-channel provider configs and returns per-provider DNS records to publish. Required role: admin or owner.

POST/v1/admin/sending-domains/:id/attach

Authenticate with a session token and X-Tenant-Slug. Required role: admin or owner.

For each provider config supplied, Nudgel calls the provider API to register the domain, records the provider-assigned DNS records, and sets verificationState to pending_dns. Publish the returned DNS records, then poll GET .../verifications or call POST .../recheck to trigger an immediate check.

Request

curl

curl -X POST https://api-raven-cloud.autotribes.app/v1/admin/sending-domains/$DOMAIN_ID/attach \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Slug: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"providerConfigIds":["postmark-config-uuid","ses-config-uuid"]}'

Body parameters

Field	Type	Notes
`providerConfigIds`	string[] · required	IDs of the provider configs to attach. Must reference email-channel providers. Obtain IDs from GET /v1/admin/providers or from the`attachableProviders` array returned when the domain was created.

Response

201 Created — array of verification objects, one per provider.

json

[
  {
    "id": "verification-uuid",
    "provider": "postmark",
    "providerConfigId": "uuid",
    "registrationState": "registered",
    "providerDomainId": "12345",
    "verificationState": "pending_dns",
    "dnsRecords": [
      {
        "type": "TXT",
        "host": "20240501._domainkey.mail.example.co.ke",
        "value": "v=DKIM1; k=rsa; p=...",
        "note": "DKIM signing key"
      },
      {
        "type": "CNAME",
        "host": "pm-bounces.mail.example.co.ke",
        "value": "pm.mtasv.net",
        "note": "Return-Path for bounce processing"
      }
    ],
    "registrationError": null,
    "lastCheckedAt": null,
    "lastCheckError": null,
    "verifiedAt": null,
    "attachedAt": "2026-05-01T12:00:01Z"
  }
]

PUBLISH DNS RECORDS BEFORE SENDING

Each verification object contains dnsRecords specific to that provider. Publish them in your DNS provider, then either wait for Nudgel's background poller (every 30 s) or call POST .../recheck to check immediately. Email sent through this domain via that provider will be held with a soft warning until the verification state reaches verified.

Errors

Status	When
`400`	`providerConfigIds` missing, empty, or references a non-email-channel provider
`401`	Invalid or expired session token
`403`	Caller does not have admin or owner role
`404`	Sending domain not found for this tenant
`409`	Domain is already attached to one of the specified providers