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

Send a batch of emails

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

A BillionSend API key (bs_…).

标头参数
Idempotency-Keystring

1 to 256 characters. A retry with the same key and the same body answers the original response instead of sending again; the same key with a different body answers 409 invalid_idempotent_request.

最小长度 1 · 最大长度 256
x-batch-validationstring

strict (default): any invalid email rejects the whole batch with that email's error, sending nothing. permissive: invalid emails are listed in errors by index and the valid ones are sent.

允许值:strictpermissive
请求体
必填application/json
SendEmailRequest 数组
fromstring必填

Sender, "Name <user@domain>" or bare address; the domain must be verified for the team

tostring | string[]必填

Recipient address or list of up to 50

显示属性
任意项:
string
string
string[]
string 数组
string
subjectstring必填

Subject line

最小长度 1 · 最大长度 998
htmlstring

HTML body; at least one of html/text is required

textstring

Plain-text body; at least one of html/text is required

ccstring | string[]

Cc address or list

显示属性
任意项:
string
string
string[]
string 数组
string
bccstring | string[]

Bcc address or list

显示属性
任意项:
string
string
string[]
string 数组
string
reply_tostring | string[]

Reply-To address or list

显示属性
任意项:
string
string
string[]
string 数组
string
scheduled_atstring

Deliver later: ISO 8601 with offset, or relative like "in 2 hours" (an ISO 8601 datetime with offset (e.g. "2026-09-01T12:00:00Z") or a relative time like "in 5 mins", "in 2 hours", or "in 1 day"); max 30 days ahead

tagsobject[]

Key/value labels attached to the email for filtering; names starting with billionsend_, in any letter case, are reserved

显示属性
object 数组
namestring必填
最小长度 1
valuestring必填
topic_idstring<uuid> | null

Topic id: recipients opted out of the topic are skipped; a send to one address that is a contact also gets that contact's unsubscribe link. A topic bound to a domain (domain_id) can be sent only from that domain (422 otherwise)

attachmentsobject[]

Attachments with base64 content (no remote paths)

显示属性
object 数组
filenamestring | boolean | null
显示属性
任意项:
string
string
boolean
boolean
null
null
contentstring
content_typestring
content_idstring

Inline part: the HTML shows it with <img src="cid:<content_id>">

最小长度 1 · 最大长度 255
pathstring
headersobject

Extra message headers (transport headers are rejected)

templateany

Not supported: any value is a 422; an email takes html and/or text

响应
200

Batch accepted

dataobject[]必填
显示属性
object 数组
idstring<uuid>必填
errorsobject[]
显示属性
object 数组
indexinteger必填
messagestring必填
400

Idempotency-Key is not 1 to 256 characters

statusCodenumber必填
namestring必填
messagestring必填
401

Missing, malformed, unknown or revoked API key

statusCodenumber必填
namestring必填
messagestring必填
403

Restricted API key

statusCodenumber必填
namestring必填
messagestring必填
404

Not found

statusCodenumber必填
namestring必填
messagestring必填
409

Idempotency conflict

statusCodenumber必填
namestring必填
messagestring必填
422

Validation error

statusCodenumber必填
namestring必填
messagestring必填
429

Sending quota exceeded, or the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumber必填
namestring必填
messagestring必填
试一试
服务器
授权
参数
请求体application/json
请求
curl -X POST 'https://api.billionsend.com/emails/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <onboarding@acme.dev>",
    "to": [
      "success@simulator.amazonses.com"
    ],
    "subject": "string",
    "html": "string",
    "text": "string",
    "cc": "string",
    "bcc": "string",
    "reply_to": "string",
    "scheduled_at": "string",
    "tags": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
    "attachments": [
      {
        "filename": "string",
        "content": "string",
        "content_type": "string",
        "content_id": "string",
        "path": "string"
      }
    ],
    "headers": {
      "property1": "string",
      "property2": "string"
    },
    "template": null
  }
]'
响应
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "errors": [
    {
      "index": 0,
      "message": "string"
    }
  ]
}

这个页面有帮助吗?