Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Forward a thread email

Forwards the email from the inbox address, quoted under “––––– Forwarded message ———” with its From, Date, Subject and To, after an optional note. Its attachments go along, with any attachments you add, within 10 MiB in all. An email that carries malware is never forwarded. Accepts an Idempotency-Key; a forward the inbox’s rules hold answers 202 with the Draft.

POST/inboxes/{inbox_id}/threads/{thread_id}/emails/{email_id}/forward
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Path parameters
inbox_idstringrequired

The inbox ID or its email address, such as support@example.com

thread_idstring<uuid>required
email_idstring<uuid>required
Header parameters
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.

min length 1 · max length 256
Request body
requiredapplication/json
tostring | string[]required

An address or a list of them; "Name <address>" works too

Show properties
Any of:
string
string
string[]
Array of string
string
ccstring | string[]

An address or a list of them; "Name <address>" works too

Show properties
Any of:
string
string
string[]
Array of string
string
bccstring | string[]

An address or a list of them; "Name <address>" works too

Show properties
Any of:
string
string
string[]
Array of string
string
htmlstring

HTML body

textstring

Plain-text body

subjectstring

1-2000 characters on one line; defaults to the thread subject with Re: or Fwd:

attachmentsobject[] | null

Files with base64 content (no remote paths), 10 MiB decoded in all; none on the shared domain. A held send keeps them with its draft

Show properties
Array of object
filenamestring | boolean | null
Show properties
Any of:
string
string
boolean
boolean
null
null
contentstring
content_typestring
content_idstring

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

min length 1 · max length 255
pathstring
requires_approvalboolean

BillionSend extension: hold the email as a draft that a person approves (202 with the Draft)

headersany

Not supported yet: only an empty value is accepted, anything else answers 422

Responses
200

Sent

idstring<uuid>required

The ID of the sent email: GET /emails/{id} reads it

thread_idstring<uuid> | nullrequired

BillionSend extension: the thread the email was sent in

202

Held for approval

objectstringrequired
Allowed:inbox_draft
idstring<uuid>required
typestringrequired
Allowed:standalonereply
tostring[] | nullrequired
ccstring[]required
bccstring[]required
subjectstring | nullrequired
htmlstring | nullrequired
textstring | nullrequired
thread_idstring<uuid> | nullrequired
reply_to_email_idstring<uuid> | nullrequired
email_idstring<uuid> | nullrequired
created_atstringrequired
updated_atstringrequired
attachmentsobject[]required

The draft's files, by position; empty once it is sent, rejected or expired

Show properties
Array of object
idstringrequired
filenamestringrequired
content_typestringrequired
sizeintegerrequired
statusstringrequired
Allowed:draftpending_approvalsentrejectedexpired
approval_reasonsstring[]required
forwardbooleanrequired
decided_bystring | nullrequired
decided_atstring | nullrequired
expires_atstring | nullrequired
send_atstring | nullrequired

BillionSend extension: when the scheduled send goes out; null when not scheduled

send_errorstring | nullrequired

BillionSend extension: the error name of the last scheduled send that was refused (e.g. invalid_api_key, inbox_send_cap_reached, not_found); null otherwise

401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Restricted API key, the inbox's or the shared domain's rules, or held mail

statusCodenumberrequired
namestringrequired
messagestringrequired
404

Not found

statusCodenumberrequired
namestringrequired
messagestringrequired
409

Idempotency conflict, or a draft already sent

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

The inbox's daily send limit, or the team's daily limit for mail from the shared domain, or the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/inboxes/string/threads/497f6eca-6276-4993-bfeb-53cbbbba6f08/emails/497f6eca-6276-4993-bfeb-53cbbbba6f08/forward' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "string",
  "cc": "string",
  "bcc": "string",
  "html": "string",
  "text": "string",
  "subject": "string",
  "attachments": [
    {
      "filename": "string",
      "content": "string",
      "content_type": "string",
      "content_id": "string",
      "path": "string"
    }
  ],
  "requires_approval": true,
  "headers": null
}'
Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84"
}

Was this page helpful?