Messages

Send an email

Submit email using the granted mailbox identity. MCP requires approval of exact recipients and content.

POST/api/v1/mailboxes/{mailboxId}/send/

Permission send

MCP actions require approval

When called through MCP, this operation returns a single-use approval link. Review and approve the exact action in CherryMail within ten minutes.

Path parameters

mailboxIdintegerrequired

The selected mailbox ID. Email access requires a current mailbox grant.

Request headers

Idempotency-Keystringrequired

A unique key for this intentional action. Reuse it only with the same request input.

Maximum 128 characters

Request body

Send JSON with Content-Type: application/json.

fromstring

Sender identity. Must exactly match the granted mailbox address.

Maximum 254 characters

tostring[]required

Recipient email addresses. To, Cc, and Bcc combined must not exceed 20.

ccstring[]

Carbon-copy recipients.

bccstring[]

Blind-carbon-copy recipients.

subjectstringrequired

The email subject, without control characters.

Maximum 998 characters

textstringrequired

Plain-text message body.

Maximum 1,000,000 characters

htmlstring

Optional HTML message body.

Maximum 1,000,000 characters

attachmentsobject[]

Files to include. Up to 10 attachments and 5 MiB decoded in total.

Show child fields

filenamestringrequired

The attachment filename.

Maximum 180 characters

contentTypestringrequired

The MIME media type, such as application/pdf.

Maximum 120 characters

contentstringrequired

The file bytes encoded as base64.

Maximum 7,000,000 characters

inReplyTostring

Message-ID used for reply threading.

Maximum 998 characters

referencesstring[]

Message-ID reference chain for threading.

Responses

200Success

Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.

400Invalid request

Invalid input or missing idempotency key.

401Unauthenticated

Missing, expired, or revoked bearer credential.

403Forbidden

Wrong credential purpose, insufficient scope, or missing mailbox grant.

404Not found

Resource or message not found or unavailable to this integration.

409Conflict

Resource conflict, stale message reference, ambiguous submission, or idempotency conflict.

413Too large

Request or message exceeds the supported size.

429Rate limited

Rate limited. Honor Retry-After before retrying.

500Internal server error

Unexpected server error. Contact support with the request ID; inspect uncertain writes before retrying.

503Service unavailable

Integrations disabled or an upstream service unavailable.

See limits and errors for retry handling and the error envelope.

Example request

curl -X POST 'https://cherrymail.net/api/v1/mailboxes/123/send/' \
  -H "Authorization: Bearer $CHERRYMAIL_API_KEY" \
  -H "Idempotency-Key: example-request-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "recipient@example.com"
  ],
  "subject": "Hello from CherryMail",
  "text": "Your first email, sent with the CherryMail API."
}'

Responseapplication/json

dataobjectrequired

Show child fields

operation_idstring · uuidrequired

Durable operation ID. Use GET /operations/{id}/ to inspect it.

statestringrequired

Values: running, pending, completed, uncertain

resultobject | nullrequired

Endpoint-specific result; null while a concurrent request is running or its outcome is uncertain.

Show child fields

statestringrequired

Value: "submitted"

messageIdstringrequired

RFC Message-ID assigned to this submission.

acceptedstring[]required

Recipients accepted by SMTP.

rejectedstring[]required

Recipients rejected by SMTP.

sentCopyobjectrequired

Show 2 object variants

Stored Sent copy

folderstringrequired

uidinteger | nullrequired

Appended message UID, or null when the IMAP server did not return it.

uidValiditystring | nullrequired

statestringrequired

Value: "stored"

Uncertain Sent copy

statestringrequired

Value: "uncertain"

messagestringrequired

SMTP succeeded, but the Sent copy needs inspection. Do not resend the email.

deliveredbooleanrequired

SMTP acceptance does not prove delivery to the recipient.

Value: false

request_idstring · uuidrequired

Request ID for support and correlation. Also returned in X-Request-ID.

Example

200 response body

{
  "data": {
    "operation_id": "6032a8b5-5ab8-4d3d-9104-d1e8162a1453",
    "state": "completed",
    "result": {
      "state": "submitted",
      "messageId": "<submission-1042@cherrymail.net>",
      "accepted": [
        "recipient@example.com"
      ],
      "rejected": [],
      "sentCopy": {
        "state": "stored",
        "folder": "Sent",
        "uid": 87,
        "uidValidity": "1730000000"
      },
      "delivered": false
    }
  },
  "request_id": "650f28e8-c344-42e4-ae43-c61539f83119"
}

Durable operation receipt with this endpoint’s result. Pending provisioning and SMTP acceptance are distinct from resource readiness and recipient delivery.

Response headers

Cache-Control: no-store

X-Request-ID

Same request ID as the JSON body.

RateLimit-Limit: 120;w=60

Per-credential limit and window.

RateLimit-Reset: 60

Rate-limit window in seconds.

Base URL
https://cherrymail.net/api/v1

View the OpenAPI contract ↗