跳到内容
Esc
↑↓导航↵打开⌘J预览

Read contacts in bulk

BillionSend extension: returns up to 1000 contacts by id or by email address in one request, in request order, optionally with their properties and topic subscriptions. Entries that match no contact are listed under missing instead of failing the call. One call counts as one request against the rate limit.

POST/contacts/batch/get
授权
AuthorizationBearer 令牌 · header必填

A BillionSend API key (bs_…).

请求体
必填application/json
contactsobject[]必填

Up to 1000 contacts, each by id or by email address (matched case-insensitively)

最少 1 项 · 最多 1000 项
显示属性
object 数组
idstring<uuid>
emailstring<email>
includestring[]

Facets to attach to every contact returned: properties and/or topics

响应
200

The contacts found, and the entries that matched none

objectstring必填
允许值:list
dataobject[]必填

The contacts found, in request order

显示属性
object 数组
idstring<uuid>必填
emailstring必填
first_namestring | null必填
last_namestring | null必填
created_atstring必填
unsubscribedboolean必填

Opt-out from every marketing send of the team, whichever domain sends. A recipient's own unsubscribe never sets it: that is recorded for the domain whose email carried the link (see unsubscribed_domains).

unsubscribed_domainsobject[]必填

BillionSend extension: the domains this contact unsubscribed from through a link in their email. Marketing sends from those domains skip the contact; other domains still reach them. The team-wide opt-out is unsubscribed, not an entry here. Remove an entry with DELETE /unsubscribes/{id}.

显示属性
object 数组
domain_idstring<uuid> | null必填

Null when the domain has since been deleted from the team

namestring必填

The domain's name

unsubscribed_atstring必填
verification_statusstring | null必填

BillionSend extension: the verdict of the contact's last deep verification (POST /verifications); null while it was never verified

允许值:validinvalidriskycatchallroledisposableunknownnull
verified_atstring | null必填

When the last deep verification finished; null while never verified

propertiesobject

Present with include=properties

topicsobject[]

Present with include=topics

显示属性
object 数组
idstring<uuid>必填
namestring必填
descriptionstring | null必填
subscriptionstring必填

Effective choice: the contact's explicit one, else the topic's default

允许值:opt_inopt_out
explicitboolean必填

True when the contact or the API chose this; false when it is the topic's default

visibilitystring必填

The hosted preference page lists public topics only

允许值:publicprivate
objectstring必填
允许值:contact
missingobject[]必填

Request entries that matched no contact of the team

显示属性
object 数组
indexinteger必填

Position in the request's contacts array

idstring<uuid>
emailstring
401

Missing, malformed, unknown or revoked API key

statusCodenumber必填
namestring必填
messagestring必填
422

Validation error

statusCodenumber必填
namestring必填
messagestring必填
429

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

statusCodenumber必填
namestring必填
messagestring必填
试一试
服务器
授权
请求体application/json
请求
curl -X POST 'https://api.billionsend.com/contacts/batch/get' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "contacts": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "user@example.com"
    }
  ],
  "include": [
    "properties"
  ]
}'
响应
{
  "object": "list",
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "created_at": "string",
      "unsubscribed": true,
      "unsubscribed_domains": [
        {
          "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
          "name": "string",
          "unsubscribed_at": "string"
        }
      ],
      "verification_status": "valid",
      "verified_at": "string",
      "properties": {
        "property1": {
          "type": "string",
          "value": "string"
        },
        "property2": {
          "type": "string",
          "value": "string"
        }
      },
      "topics": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "description": "string",
          "subscription": "opt_in",
          "explicit": true,
          "visibility": "public"
        }
      ],
      "object": "contact"
    }
  ],
  "missing": [
    {
      "index": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "string"
    }
  ]
}

这个页面有帮助吗?