List sending domains

GET

/v1/email/domains

for await (const domain of bird.domains.list()) {
  console.log(domain.id, domain.status);
}

for domain in client.domains.list():
    print(domain.id, domain.status)

for domain, err := range client.Domains.List(context.Background(), bird.DomainListParams{Limit: 50}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(domain.Id, *domain.Status)
}

foreach ($bird->domains->list() as $domain) {
    echo $domain->getId(), ' ', $domain->getStatus(), "\n";
}

bird email domains list

curl -X GET "https://us1.platform.bird.com/v1/email/domains" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "sort=created_at" \
  --url-query "order=desc" \
  --url-query "limit=25" \
  --url-query "include_total=false"

Réponse200

{
  "data": [
    {
      "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "domain": "mail.acme.com",
      "vendor": "other",
      "status": "pending",
      "next": [
        {
          "kind": "operation"
        }
      ],
      "dkim": {
        "mode": "txt",
        "selector": "bird1",
        "key_size": 2048
      },
      "capabilities": {
        "sending": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "return_path": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "dmarc": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "tracking": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "inbound": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        }
      },
      "receiving": {
        "state": "enabled"
      },
      "dns_records": [
        {
          "type": "TXT",
          "purpose": "dkim",
          "state": "active",
          "status": "pending"
        }
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns all sending domains for the current workspace, newest first by default. Each item is the full domain object, including capability statuses and dns_records, so no per-domain follow-up read is needed. Filter with name to find a specific domain.

Paramètres de requête

namestring

Substring match against the domain name (case-insensitive).

sortstring

Field to sort by. Defaults to created_at.

Possible values: created_at, name

orderstring

Sort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

Possible values: asc, desc

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

include_totalboolean

When true, the response includes a total field with the total number of items matching the request's filters across all pages.

Contenu de la réponse

data

array of object

obligatoire

Page of sending domains, newest first by default.

Afficher les attributs enfants

data.id

string

obligatoire

data.workspace_id

string

obligatoire

data.domain

string

obligatoire

The sending domain name. Set at creation and immutable.

data.vendor

string

obligatoire

The DNS provider hosting this domain's nameservers, so you know which provider's dashboard to manage the required DNS records in. Returns other when the provider has not been detected or is not recognized.

Possible values: other, cloudflare, route53, godaddy, namecheap, google, azure, digitalocean, squarespace

data.status

string

obligatoire

Domain ownership verification, proven by the DKIM record. Readiness to send or track is reported separately per capability under capabilities.*.status.

pending: the DKIM record has not been published yet.
verified: the DKIM record is in place; ownership is confirmed.
failed: a DKIM record exists but does not match the expected value (for example a stale record from an earlier setup), or a previously verified record was removed. Correct the record to recover.
temporary_failure: DNS resolution failed transiently, such as from a timeout or unreachable nameserver. Verification retries automatically; do not change the DNS records unless they are incorrect.
rejected: the domain was refused for policy reasons and cannot be used for sending. Contact support if you believe this is an error.

Possible values: pending, verified, failed, temporary_failure, rejected

data.settings

object

obligatoire

Per-domain behavior toggles. Changes apply immediately to new sends.

Afficher les attributs enfants

data.next

array of object

What to do next about this domain, given the state it is in. Each entry names one action and says why it is worth taking, so you can act on this response without working out the order yourself. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.

This answers whether you own the domain, which is what status reports. What each capability still needs before it can send or receive is reported separately under capabilities, so an empty list here does not on its own mean the domain is ready.

Afficher les attributs enfants

data.dkim

object

obligatoire

Active DKIM signing configuration for the domain.

Afficher les attributs enfants

data.capabilities

object

obligatoire

Afficher les attributs enfants

data.receiving

object

obligatoire

Receiving state and whether it is managed from another workspace.

Afficher les attributs enfants

data.dns_records

array of object

obligatoire

The domain's DNS records and their individual verification state, returned in full on both the list and single-domain responses. This is the complete set to publish across DKIM, return-path, DMARC, tracking, and inbound; records for a staged change carry state: pending. Inbound MX records are always included as a regional reference, even while receiving is off and capabilities.inbound.status is not_configured. Their presence alone does not mean receiving is enabled; see DomainUpdate.inbound.

Afficher les attributs enfants

data.last_checked_at

nullable string

When we last checked this domain's DNS records, whether or not the outcome changed. Updated on every verification: your manual refresh and the periodic automatic re-checks alike. null if the domain has never been checked.

data.verified_at

nullable string

When the domain's ownership was confirmed: the moment status became verified via the DKIM record. Unchanged by later re-checks while it stays verified. null if the domain has never been verified.

data.created_at

string

obligatoire

When the domain was added.

data.updated_at

string

obligatoire

When the domain's configuration was last changed (such as a settings or return-path change). Verification re-checks do not change this; see last_checked_at and verified_at for verification timing.

next_cursor

nullable string

obligatoire

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor

nullable string

obligatoire

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor

nullable string

obligatoire

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

total

nullable integer

Total number of items matching the request's filters across all pages. Present only when include_total=true was passed; otherwise null.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation

for await (const domain of bird.domains.list()) {
  console.log(domain.id, domain.status);
}

for domain in client.domains.list():
    print(domain.id, domain.status)

for domain, err := range client.Domains.List(context.Background(), bird.DomainListParams{Limit: 50}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(domain.Id, *domain.Status)
}

foreach ($bird->domains->list() as $domain) {
    echo $domain->getId(), ' ', $domain->getStatus(), "\n";
}

bird email domains list

curl -X GET "https://us1.platform.bird.com/v1/email/domains" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "sort=created_at" \
  --url-query "order=desc" \
  --url-query "limit=25" \
  --url-query "include_total=false"

Réponse200

{
  "data": [
    {
      "id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "domain": "mail.acme.com",
      "vendor": "other",
      "status": "pending",
      "next": [
        {
          "kind": "operation"
        }
      ],
      "dkim": {
        "mode": "txt",
        "selector": "bird1",
        "key_size": 2048
      },
      "capabilities": {
        "sending": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "return_path": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "dmarc": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "tracking": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        },
        "inbound": {
          "status": "verified",
          "pending": {
            "domain": "rp.mail.acme.com",
            "status": "pending"
          }
        }
      },
      "receiving": {
        "state": "enabled"
      },
      "dns_records": [
        {
          "type": "TXT",
          "purpose": "dkim",
          "state": "active",
          "status": "pending"
        }
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

List sending domains

Paramètres de requête

Contenu de la réponse

Ressources associées