Axuz Developers

POST /messages

Compose — salva rascunho OU envia (interno/externo)

  • Acesso: Login
  • Serviço: https://mail-api.axuz.net

Autenticação aceita

  • sessionCookie — Sessão plena Axuz (cookie de sessão da casa). Sessão restrita é 403 enrollment_required.
  • bearerSession — JWT de acesso da sessão em `Authorization: Bearer`.

- send=false → grava row draft no folder drafts. - send=true interno-only → grava sent no remetente + received em cada destinatário interno (mesma tx). - send=true com destinatário externo → depende do gate MAIL_EXTERNAL_SEND_ENABLED. Ligado: enfileira em mail_outbound_log + dispara Deliver ao MTA. Desligado (default): responde 503 pending_stalwart ANTES de escrever nada. (piso §37.15 / MAIL-03)

Parâmetros

Sem parâmetros.

Corpo da requisição

application/json · Obrigatório

NomeTipoObrigatórioDescrição
account_idstring<uuid>sim
toarray<string<email>>não
ccarray<string<email>>não
bccarray<string<email>>não
subjectstringnão
body_htmlstringnão
body_textstringnão
in_reply_tostring<uuid> | nullnão
sendbooleannão

false = grava rascunho no folder drafts. true = tenta envio (routing interno + externo). Externo respeita o gate §37.15.

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "to": [
    "pessoa@example.test"
  ],
  "cc": [
    "pessoa@example.test"
  ],
  "bcc": [
    "pessoa@example.test"
  ],
  "subject": "string",
  "body_html": "string",
  "body_text": "string",
  "in_reply_to": "00000000-0000-0000-0000-000000000000",
  "send": false
}

Respostas

201

Rascunho salvo ou mensagem enviada

NomeTipoObrigatórioDescrição
messageMailMessagesim
message.idstring<uuid>sim
message.account_idstring<uuid>sim
message.folder_idstring<uuid>sim
message.thread_idstring<uuid>sim
message.in_reply_tostring<uuid> | nullnão
message.from_emailstring<email>sim
message.from_namestringnão
message.to_emailsarray<string<email>>sim
message.cc_emailsarray<string<email>>não
message.bcc_emailsarray<string<email>>não
message.subjectstringsim
message.body_htmlstringnão

Corpo HTML sanitizado (allowlist bluemonday, internal/sanitize). Toda leitura passa pelo mesmo chokepoint (scanMessage), então este campo nunca carrega <script>, atributos on*, javascript:, <iframe>, <object> ou <svg>. A COLUNA homônima no banco guarda o corpo cru (forense) e NÃO é confiável — ela nunca sai pela API.

message.body_textstringnão
message.readbooleansim
message.starredbooleansim
message.labelsarray<string>não
message.received_atstring<date-time>sim
message.sent_atstring<date-time> | nullnão
message.statusstringsim

enum: "draft", "sent", "received", "queued"

message.internalbooleansim
message.created_atstring<date-time>sim
message.updated_atstring<date-time>sim
internalbooleansim

True quando todos os destinatários bateram em mail_accounts.email.

externalbooleansim

True quando pelo menos um destinatário é externo (delegado ao MTA).

400

Payload inválido

401

Sem credencial valida

NomeTipoObrigatórioDescrição
errorstringsim

403

Remetente não pertence ao usuário

404

Account not found

429

Teto de envio (F-019) atingido. Header Retry-After em segundos. Só ocorre com send=true — rascunho não consome cota.

NomeTipoObrigatórioDescrição
errorstringsim
layerstringsim

Camada que negou.

enum: "user", "mailbox", "pair", "team"

limitintegersim

Teto da camada que negou.

usedintegersim

Consumido na janela quando negou.

retry_afterintegersim

Segundos até a próxima vaga (mínimo 1).

messagestringsim

500

Erro interno. Tente de novo com backoff; reporte o X-Request-Id.

NomeTipoObrigatórioDescrição
errorstringsim

503

External send disabled — gate §37.15 rejeitou antes de qualquer INSERT.

NomeTipoObrigatórioDescrição
errorstringsim
statusstringsim

Exemplos

O "Try it" está desligado nesta referência. Use os exemplos com a sua credencial de teste.

curl

curl -sS -X POST 'https://mail-api.axuz.net/messages' \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"00000000-0000-0000-0000-000000000000","to":["pessoa@example.test"],"cc":["pessoa@example.test"],"bcc":["pessoa@example.test"],"subject":"string","body_html":"string","body_text":"string","in_reply_to":"00000000-0000-0000-0000-000000000000","send":false}'

Node.js

const res = await fetch("https://mail-api.axuz.net/messages", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AXUZ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "account_id": "00000000-0000-0000-0000-000000000000",
    "to": [
      "pessoa@example.test"
    ],
    "cc": [
      "pessoa@example.test"
    ],
    "bcc": [
      "pessoa@example.test"
    ],
    "subject": "string",
    "body_html": "string",
    "body_text": "string",
    "in_reply_to": "00000000-0000-0000-0000-000000000000",
    "send": false
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://mail-api.axuz.net/messages",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    json={
        "account_id": "00000000-0000-0000-0000-000000000000",
        "to": [
            "pessoa@example.test",
        ],
        "cc": [
            "pessoa@example.test",
        ],
        "bcc": [
            "pessoa@example.test",
        ],
        "subject": "string",
        "body_html": "string",
        "body_text": "string",
        "in_reply_to": "00000000-0000-0000-0000-000000000000",
        "send": False,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())