Skip to content
adaptmailAPI
English

Send a message

API 0.16.0OpenAPIllms-full.txt
POST/v1/mailboxes/{mailbox_id}/send

Idempotency-Key is required and must contain 8–128 characters. Repeating the same key and body returns the same operation; a different body returns 409. HTTP 202 means queued. Check the operation status to determine the outcome.

Authentication and access · Errors and retries

Request

Terminal window
curl -X POST 'https://adapt-mail.com/v1/mailboxes/<mailbox_id>/send' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Idempotency-Key: message-20261019-0001' \
  -H 'Content-Type: application/json' \
  --data '{"to":["[email protected]"],"subject":"Hello","text":"A message from Adapt Mail"}'

Parameters

mailbox_idpathNecessarily

integer

X-Customer-IDheader
Option 1

string

Option 2

null

Idempotency-KeyheaderNecessarily

string

minLength: 8

maxLength: 128

Request body · application/json

object

toNecessarily

array

Addresses of the main recipients.

minItems: 1

maxItems: 50

Array elements

string

cc

array

Copy recipient addresses that are visible to other participants.

maxItems: 50

Array elements

string

bcc

array

Bcc recipient addresses.

maxItems: 50

Array elements

string

subject

string

Subject of the message.

Default: ""

maxLength: 998

text

string

The text of the message without formatting.

Default: ""

maxLength: 200000

html

HTML-formatted version of the message.

Option 1

string

maxLength: 300000

Option 2

null

file_ids

array

ID previously downloaded files in this mailbox. Get them when downloading or from the list of files.

maxItems: 20

Array elements

string · uuid

forward_message

The original email whose attachments need to be forwarded.

Option 1

object

folderNecessarily

string

Folder name from the folder list, for example INBOX.

minLength: 1

maxLength: 255

uidvalidityNecessarily

integer

The value is uidvalidity from the response API for this folder.

exclusiveMinimum: 0

uidNecessarily

integer

exclusiveMinimum: 0

Unknown fields are not accepted.

Option 2

null

reply_to_message_id

The message_id value of the email you are replying to.

Option 1

string

maxLength: 998

Option 2

null

references

The value references of the original message to save the reply chain.

Option 1

string

maxLength: 4000

Option 2

null

send_at

Delayed dispatch time with time zone, for example 2026-11-01T12:00:00Z. Without a value, dispatch begins as the queue is processed.

Option 1

string · date-time

Option 2

null

Unknown fields are not accepted.

Responses

202 Successful response

application/json

object

id

string · uuid

Operation ID for checking the status and canceling a pending submission.

kind

string

mailbox_id
Option 1

integer

Option 2

null

status

string

Valid values: "queued" "running" "succeeded" "failed" "uncertain" "cancelled"

run_at

string

Date and time in UTC. If there is no offset, the value also represents UTC.

created_at

string

Date and time in UTC. If there is no offset, the value also represents UTC.

completed_at
Option 1

string

Date and time in UTC. If there is no offset, the value also represents UTC.

Option 2

null

error

The reason for the error if the operation did not complete successfully.

Option 1

string

Option 2

null

result

The result of the operation. For sending, contains information about accepted and rejected recipients.

Option 1

object

Option 2

null

400 Invalid header or identifier

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

401 Login required

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

403 No access

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

404 Resource not found

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

409 State conflict

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

413 Size limit exceeded

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

422 Validation error

application/json

object

detail

array

Array elements

object

locNecessarily

array

Array elements
Option 1

string

Option 2

integer

msgNecessarily

string

typeNecessarily

string

503 Temporarily unavailable

application/json

object

detail
Option 1

string

Option 2

object

code

string

message

string

Option 3

array

Array elements

object

Successful send result

Fields in the operation’s result after execution. These are not returned when the message is first queued.

object

message_id

string

smtp_accepted

boolean

sent_saved

boolean

accepted_recipients

array

Array elements

string

rejected_recipients

array

Array elements

object

email

string

code

integer