Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu

Send a batch of emails

POST/emails/batch
Autorisation
AuthorizationJeton Bearer · headerrequis

A BillionSend API key (bs_…).

Paramètres d'en-tête
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.

longueur min 1 · longueur max 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.

Valeurs autorisées :strictpermissive
Corps de la requête
requisapplication/json
Tableau de SendEmailRequest
fromstringrequis

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

tostring | string[]requis

Recipient address or list of up to 50

Afficher les propriétés
Au moins un de :
string
string
string[]
Tableau de string
string
subjectstringrequis

Subject line

longueur min 1 · longueur max 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

Afficher les propriétés
Au moins un de :
string
string
string[]
Tableau de string
string
bccstring | string[]

Bcc address or list

Afficher les propriétés
Au moins un de :
string
string
string[]
Tableau de string
string
reply_tostring | string[]

Reply-To address or list

Afficher les propriétés
Au moins un de :
string
string
string[]
Tableau de 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

Afficher les propriétés
Tableau de object
namestringrequis
longueur min 1
valuestringrequis
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)

Afficher les propriétés
Tableau de object
filenamestring | boolean | null
Afficher les propriétés
Au moins un de :
string
string
boolean
boolean
null
null
contentstring
content_typestring
content_idstring

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

longueur min 1 · longueur max 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

Réponses
200

Batch accepted

dataobject[]requis
Afficher les propriétés
Tableau de object
idstring<uuid>requis
errorsobject[]
Afficher les propriétés
Tableau de object
indexintegerrequis
messagestringrequis
400

Idempotency-Key is not 1 to 256 characters

statusCodenumberrequis
namestringrequis
messagestringrequis
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequis
namestringrequis
messagestringrequis
403

Restricted API key

statusCodenumberrequis
namestringrequis
messagestringrequis
404

Not found

statusCodenumberrequis
namestringrequis
messagestringrequis
409

Idempotency conflict

statusCodenumberrequis
namestringrequis
messagestringrequis
422

Validation error

statusCodenumberrequis
namestringrequis
messagestringrequis
429

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

statusCodenumberrequis
namestringrequis
messagestringrequis
Essayer
Serveur
Autorisation
Paramètres
Corpsapplication/json
Requête
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
  }
]'
Réponse
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  ],
  "errors": [
    {
      "index": 0,
      "message": "string"
    }
  ]
}

Cette page vous a-t-elle été utile ?