Axuz Developers

POST /v1/send

Envia email via API key

  • Acesso: Membro da equipe
  • 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`.

Rate-limited por chave. Gate mail:send scope obrigatório. Gate §37.15 (MAIL-04): destinatário externo com MAIL_EXTERNAL_SEND_ENABLED=false devolve 503 e NÃO conta contra mail_api_usage. Outros paths (2xx/400) contam.

Parâmetros

Sem parâmetros.

Corpo da requisição

application/json · Obrigatório

NomeTipoObrigatórioDescrição
fromstring<email>sim
toarray<string<email>>sim
ccarray<string<email>>não
bccarray<string<email>>não
reply_tostringnão
subjectstringsim
htmlstringnão
textstringnão
headersobjectnão
attachmentsarray<MailSendAttachment>não
attachments[].filenamestringsim
attachments[].content_base64string<byte>sim
attachments[].content_typestringnão
{
  "from": "pessoa@example.test",
  "to": [
    "pessoa@example.test"
  ],
  "cc": [
    "pessoa@example.test"
  ],
  "bcc": [
    "pessoa@example.test"
  ],
  "reply_to": "string",
  "subject": "string",
  "html": "string",
  "text": "string",
  "headers": {},
  "attachments": [
    {
      "filename": "string",
      "content_base64": "string",
      "content_type": "application/octet-stream"
    }
  ]
}

Respostas

201

Aceito para entrega

NomeTipoObrigatórioDescrição
message_idstring<uuid>sim
statusstringsim

sent quando todos os destinatários eram internos; queued quando existe destinatário externo (delegado ao MTA).

enum: "sent", "queued"

internalbooleansim
externalbooleansim

400

Erro de validação (from inválido, allowed_from denied, folder miss, etc)

401

Chave ausente/inválida

403

Chave revogada ou scope mail:send ausente

429

Duas causas distintas, ambas com Retry-After: rate limit de API da chave (requisições/minuto, corpo {"error": ...}) ou teto de ENVIO F-019 (mensagens/janela, corpo SendRateLimit). O teto de envio NÃO conta como uso em mail_api_usage.

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 (não conta como uso)

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/v1/send' \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"pessoa@example.test","to":["pessoa@example.test"],"cc":["pessoa@example.test"],"bcc":["pessoa@example.test"],"reply_to":"string","subject":"string","html":"string","text":"string","headers":{},"attachments":[{"filename":"string","content_base64":"string","content_type":"application/octet-stream"}]}'

Node.js

const res = await fetch("https://mail-api.axuz.net/v1/send", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AXUZ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "from": "pessoa@example.test",
    "to": [
      "pessoa@example.test"
    ],
    "cc": [
      "pessoa@example.test"
    ],
    "bcc": [
      "pessoa@example.test"
    ],
    "reply_to": "string",
    "subject": "string",
    "html": "string",
    "text": "string",
    "headers": {},
    "attachments": [
      {
        "filename": "string",
        "content_base64": "string",
        "content_type": "application/octet-stream"
      }
    ]
  }),
});
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/v1/send",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    json={
        "from": "pessoa@example.test",
        "to": [
            "pessoa@example.test",
        ],
        "cc": [
            "pessoa@example.test",
        ],
        "bcc": [
            "pessoa@example.test",
        ],
        "reply_to": "string",
        "subject": "string",
        "html": "string",
        "text": "string",
        "headers": {},
        "attachments": [
            {
                "filename": "string",
                "content_base64": "string",
                "content_type": "application/octet-stream",
            },
        ],
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())