Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau

Update a domain

PATCH/domains/{id}
Autorisierung
AuthorizationBearer-Token · headererforderlich

A BillionSend API key (bs_…).

Pfadparameter
idstring<uuid>erforderlich
Request-Body
application/json
click_trackingboolean

Rewrite links to redirect through the tracking host and record email.clicked events. Off by default.

open_trackingboolean

Inject a tracking pixel served from the tracking host and record email.opened events. Off by default.

tracking_subdomainstring | null

DNS label of the domain's own tracking host, e.g. "links" for links.<domain>. Optional: without one, tracked links use the shared tracking host. Setting it adds a Tracking CNAME to records[] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Tracking record then reads verified, and links go through it from then on. A subdomain that does not activate within 72 hours reads failed; send the same tracking_subdomain again to retry. Empty string or null clears it.

unsubscribe_subdomainstring | null

BillionSend extension: DNS label of the domain's own unsubscribe host, e.g. "unsubscribe" for unsubscribe.<domain>. Optional: without one, unsubscribe links (and the List-Unsubscribe header) use the shared unsubscribe host. Setting it adds an Unsubscribe CNAME to records[] (point it at the given value, DNS only); its certificate is issued automatically once it resolves, the Unsubscribe record then reads verified, and unsubscribe links go through it from then on. The same label as tracking_subdomain is allowed: one host then serves both and records[] shows one row. A subdomain that does not activate within 72 hours reads failed; send the same unsubscribe_subdomain again to retry. Kept apart from tracking_subdomain because ad blockers filter tracking hosts by name. Empty string or null clears it.

unsubscribe_pageobject

BillionSend extension: this domain's own look for its unsubscribe pages. Fields not sent keep their value; null clears one, and a cleared field falls back to the team's default page. logo_url is read-only here: the logo is uploaded in the dashboard.

Eigenschaften anzeigen
brand_namestring | null

Name shown on the page; max 80 characters

max. Länge 80
messagestring | null

Text above the unsubscribe button; max 500 characters

max. Länge 500
success_messagestring | null

Text shown once the choice is saved; max 500 characters

max. Länge 500
redirect_urlstring | null

Where the recipient goes after unsubscribing instead of the in-page message; http(s) only

background_colorstring | null

Page background, #rrggbb

text_colorstring | null

Page text color, #rrggbb

accent_colorstring | null

Button and link color, #rrggbb

logo_radiusstring | null

Corner radius of the logo: square, gentle, rounded or circle

Erlaubt:squaregentleroundedcirclenull
tlsany
capabilitiesobject

What the domain is used for (sending, receiving); omitted fields keep their value.

Eigenschaften anzeigen
sendingstring

Only enabled is accepted: a domain of your own can't be receive-only, so disabled is a 422.

Erlaubt:enableddisabled
receivingstring

Inbound mail for every address at the domain (a catch-all), readable at /emails/receiving and announced by the email.received webhook. Enabling needs a verified domain, and adds a Receiving MX record to records[]. A domain that already has mailboxes is best received on a subdomain (inbound.example.com): the Receiving MX would take their mail.

Erlaubt:enableddisabled
receiving_catch_allboolean

BillionSend extension: store mail to addresses without an inbox (true) or refuse it at RCPT (false). Turning it on needs receiving enabled and a paid plan.

Antworten
200

Domain updated; full object with records

idstring<uuid>erforderlich
namestringerforderlich
statusstringerforderlich
created_atstringerforderlich
regionstringerforderlich
open_trackingbooleanerforderlich
click_trackingbooleanerforderlich
tracking_subdomainstring | nullerforderlich
tracking_statusstring | nullerforderlich

BillionSend extension: where the tracking subdomain stands: pending (waiting for its CNAME and certificate), active (links go through it) or failed (did not activate within 72 hours; links use the shared host). null while no tracking_subdomain is set.

Erlaubt:pendingactivefailednull
tracking_errorstring | nullerforderlich

BillionSend extension: why the tracking subdomain is not active, when known

unsubscribe_subdomainstring | nullerforderlich

BillionSend extension: the domain's own unsubscribe host label, null when unset

unsubscribe_statusstring | nullerforderlich

BillionSend extension: where the unsubscribe subdomain stands: pending, active (unsubscribe links go through it) or failed (links use the shared host). null while no unsubscribe_subdomain is set. When both subdomains are the same label they share one host and always read the same.

Erlaubt:pendingactivefailednull
unsubscribe_errorstring | nullerforderlich

BillionSend extension: why the unsubscribe subdomain is not active, when known

unsubscribe_pageobjecterforderlich

BillionSend extension: this domain's own look for its unsubscribe pages. A null field falls back to the team's default page, then to the built-in default.

Eigenschaften anzeigen
brand_namestring | nullerforderlich
messagestring | nullerforderlich
success_messagestring | nullerforderlich
redirect_urlstring | nullerforderlich
background_colorstring | nullerforderlich
text_colorstring | nullerforderlich
accent_colorstring | nullerforderlich
logo_radiusstring | nullerforderlich
Erlaubt:squaregentleroundedcirclenull
logo_urlstring | nullerforderlich

Read-only; uploaded in the dashboard

capabilitiesobjecterforderlich
Eigenschaften anzeigen
sendingstringerforderlich

enabled; on the shared row, disabled while sending from the shared domain is paused

receivingstringerforderlich

enabled while the domain receives mail

receiving_catch_allbooleanerforderlich

BillionSend extension: whether mail to an address without an inbox is stored (true) or refused at RCPT (false)

sharedbooleanerforderlich

BillionSend extension: true on the team's subdomain of the shared inbox domain, a read-only row listed after the team's own domains (403 on changes) that POST /inboxes domain_id takes; false on the team's own domains

sending_modestring

BillionSend extension, on the shared row only: what its inboxes' addresses may send. open starts conversations, reply_only replies inside their threads, receive_only sends nothing. Holds on names still apply per send: an address whose username or from_name imitates a brand, or one on an older label that does, replies only, even when the mode is open.

Erlaubt:openreply_onlyreceive_only
sending_mode_reasonstring | null

BillionSend extension, on the shared row only: what holds sending below open: plan when the team's plan holds it, the other value when the platform's sending switches do; null when open

Erlaubt:planinstancenull
objectstringerforderlich
Erlaubt:domain
recordsobject[]erforderlich
Eigenschaften anzeigen
Array von object
recordstringerforderlich

Which record this is: DKIM, SPF (the MAIL FROM MX and TXT rows), DMARC, Tracking (the tracking subdomain's CNAME, present once a tracking subdomain is set), Unsubscribe (the unsubscribe subdomain's CNAME, present once an unsubscribe subdomain is set to a label other than the tracking one) or Receiving (the MX inbound mail needs, present while receiving is enabled; it reads verified only when it is among the domain's lowest-numbered MX records). Only the DKIM and SPF rows gate sending.

namestringerforderlich
typestringerforderlich
ttlstringerforderlich
statusstringerforderlich

not_started | pending | verified | failed. DKIM and SPF rows combine public DNS with the provider's verification: found in DNS but not yet confirmed reads pending, a different published value reads failed, no record reads not_started. DMARC reads verified when a policy covers the domain — its own or a parent domain's (see inherited_from) — and not_started when none does. Tracking and Unsubscribe read verified once their CNAME resolves and its certificate is issued, pending until then, and failed when it did not activate within 72 hours.

valuestringerforderlich
prioritynumber
livestring

What public DNS answers for this record right now: found, missing, mismatch (a different value is published) or unknown (the lookup did not conclude). Omitted when no live check ran (the create response).

Erlaubt:foundmissingmismatchunknown
detailstring

One sentence explaining a row that is not verified: found but awaiting the provider, the value that is published instead, no record at the name, or which parent DMARC policy covers the domain. Omitted when there is nothing to add.

inherited_fromstring

DMARC only: the _dmarc name whose policy covers this domain when it has no record of its own (RFC 7489 organizational-domain fallback).

policystring

DMARC only, alongside inherited_from: the inherited policy's p= value.

Erlaubt:nonequarantinereject
401

Missing, malformed, unknown or revoked API key

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
403

Catch-all receiving or an own tracking / unsubscribe subdomain needs a paid plan, or the team's subdomain of the shared domain, which is read-only

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
404

Not found, or a domain other than the one the calling key is held to

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
409

Another team receives mail for this domain

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
422

Validation error

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
Ausprobieren
Server
Autorisierung
Parameter
Bodyapplication/json
Anfrage
curl -X PATCH 'https://api.billionsend.com/domains/497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "click_tracking": true,
  "open_tracking": true,
  "tracking_subdomain": "string",
  "unsubscribe_subdomain": "string",
  "unsubscribe_page": {
    "brand_name": "string",
    "message": "string",
    "success_message": "string",
    "redirect_url": "string",
    "background_color": "string",
    "text_color": "string",
    "accent_color": "string",
    "logo_radius": "square"
  },
  "tls": null,
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving_catch_all": true
}'
Antwort
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "status": "string",
  "created_at": "string",
  "region": "string",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "string",
  "tracking_status": "pending",
  "tracking_error": "string",
  "unsubscribe_subdomain": "string",
  "unsubscribe_status": "pending",
  "unsubscribe_error": "string",
  "unsubscribe_page": {
    "brand_name": "string",
    "message": "string",
    "success_message": "string",
    "redirect_url": "string",
    "background_color": "string",
    "text_color": "string",
    "accent_color": "string",
    "logo_radius": "square",
    "logo_url": "string"
  },
  "capabilities": {
    "sending": "string",
    "receiving": "string"
  },
  "receiving_catch_all": true,
  "shared": true,
  "sending_mode": "open",
  "sending_mode_reason": "plan",
  "object": "domain",
  "records": [
    {
      "record": "string",
      "name": "string",
      "type": "string",
      "ttl": "string",
      "status": "string",
      "value": "string",
      "priority": 0,
      "live": "found",
      "detail": "string",
      "inherited_from": "string",
      "policy": "none"
    }
  ]
}

War diese Seite hilfreich?