Draft an email with AI

POST/api/v1/mailbox/ai/compose
Requires amailbox token— it acts as one mailbox holder, not as the organization.

Writes or rewrites a draft from an instruction. Only when capabilities.ai is true and the holder has accepted the AI terms (POST /ai/consent).

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
502 The AI service did not answer usefully.
503 No AI is set up on this server.

Request body

  • instructionstringrequired

    What to write, in plain words, up to 2,000 characters.

  • existing_draftstring or null

    A draft to rewrite instead of starting fresh.

Request

POST/api/v1/mailbox/ai/compose
curl -X POST 'https://courier.mailyte.com/api/v1/mailbox/ai/compose' \
  -H 'Authorization: Bearer MAILBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "instruction": "Thank Tunde for the figures and ask for the Q4 forecast by Friday.",
    "existing_draft": null
  }'

Response

Successful Response

  • dataobject
    • draftstring
    • ai_calls_remaininginteger
200application/json
{
  "type": "success",
  "msg": "Draft generated",
  "data": {
    "draft": "Hi Tunde,\n\nThank you for the Q3 figures...",
    "ai_calls_remaining": 47
  }
}

Returned inside the standard envelope.

Errors

StatusWhen
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
422Validation Error
502The AI service did not answer usefully.
503No AI is set up on this server.

Every status, with what causes it and what to do, is on the error reference.