Documentação API

Referência completa para integrar qualquer sistema interno da B20 à B20Mail. A API é REST, aceita JSON e autentica por API Key via header.

VISÃO GERAL

A B20Mail é o único ponto de acesso ao Amazon SES na B20. Nenhum sistema deve configurar credenciais AWS diretamente — todos os envios passam por esta API.

AUTENTICAÇÃO

Toda requisição às rotas protegidas deve incluir o header x-api-key com a chave do projeto. Sua chave fica no painel, na aba API Keys — é uma sequência de 64 caracteres hexadecimais.

# Header obrigatório em todas as requisições autenticadas
x-api-key: <cole aqui a chave de 64 caracteres do seu projeto>

RATE LIMITING

Cada API Key possui um limite de requisições por minuto configurado no .env (padrão: 60 req/min). Ao exceder, a API retorna 429 Too Many Requests.

FORMATO DE RESPOSTA

Todas as respostas seguem o mesmo envelope JSON:

{
  "success":    true | false,
  "message":    "Mensagem descritiva",
  "request_id": "uuid-para-rastreio",
  // campos extras dependendo da rota
}

ENDPOINTS

# Resposta 200
{
  "success":    true,
  "message":    "pong",
  "version":    "1.0.0",
  "env":        "local",
  "time":       "2026-05-18 16:00:00"
}

Body da Requisição

# Exemplo completo
POST /send-email
Content-Type: application/json

{
  "from":      "Sua Empresa <[email protected]>",
  "to":        "[email protected]",
  "subject":   "Bem-vindo à B20!",
  "template":  "welcome",
  "type":      "transactional",
  "variables": {
    "name": "João Silva",
    "link": "https://seusistema.com/comecar"
  }
}

// Response 200 — o e-mail entra na FILA e é enviado pelo worker em segundos.
{
  "success":    true,
  "message":    "Email enfileirado com sucesso",
  "request_id": "a1b2c3-...",
  "message_id": null
}
// message_id fica null na resposta (o envio é assíncrono). Consulte o
// status final e o message_id da AWS depois via GET /logs.

Query Parameters

# Exemplo de Requisição (cURL)
curl -X GET "https://api.b20mail.com/logs?limit=100&status=failed" \
     -H "x-api-key: SUA_CHAVE_AQUI"

// Response 200
{
  "success": true,
  "message": "Logs recuperados",
  "request_id": "xyz-...",
  "count": 100,
  "limit": 100,
  "offset": 0,
  "logs": [
    {
      "request_id": "abc-...",
      "recipient": "[email protected]",
      "status": "failed",
      "error_message": "Bounce detectado",
      "created_at": "2026-06-15 14:00:00"
    }
  ]
}

Query Parameters

# Exemplo de Requisição
GET /stats?period=7d

// Response 200
{
  "success": true,
  "message": "Stats OK",
  "request_id": "xyz-...",
  "period": "7d",
  "overview": {
    "total": 1462,
    "sent": 1450,
    "failed": 12,
    "opened": 840
  },
  "timeline": [
    { "label": "2026-06-12", "total": 502, "sent": 500, "failed": 2, "opened": 280, "transactional": 300, "marketing": 200 },
    { "label": "2026-06-13", "total": 960, "sent": 950, "failed": 10, "opened": 560, "transactional": 650, "marketing": 300 }
  ]
}

TEMPLATES DISPONÍVEIS

ENVIANDO SEU PRÓPRIO HTML (CUSTOM)

Se você não quiser usar os templates da B20Mail, você pode desenhar e enviar o seu próprio código HTML cru. Basta omitir a variável template e preencher a variável html na requisição JSON.

SINTAXE DE VARIÁVEIS

Use {{variavel}} nos templates. As variáveis são sanitizadas automaticamente contra XSS.

<!-- No template HTML -->
<p>Olá, {{name}}!</p>
<a href="{{link}}">Recuperar senha</a>

TUTORIAL: CLASSE DE INTEGRAÇÃO COMPLETA (PHP)

Abaixo apresentamos um exemplo de classe Mailer.php pronta para uso em produção, ideal para projetos PHP (puros ou frameworks). Ela demonstra como ler as configurações do .env, processar o envio inteligente (priorizando arquivos HTML locais com fallback para a B20Mail) e tratar retornos e logs de erro.

1. Configuração do .env

# Arquivo .env do seu projeto
B20MAIL_API_URL="https://api.b20mail.com"
B20MAIL_API_KEY="SUA_CHAVE_AQUI"
MAIL_FROM_ADDRESS="Sua Empresa <[email protected]>"

2. Classe Mailer.php

<?php
/**
 * Classe de Integração SaaS — B20Mail
 */

class Mailer {
    /**
     * Dispara um e-mail via B20Mail API
     */
    public static function send(string $to, string $subject, array $variables = [], string $templateName = 'default', string $type = 'transactional'): bool {
        $apiKey = trim($_ENV['B20MAIL_API_KEY'] ?? getenv('B20MAIL_API_KEY') ?? '', '"\'');
        
        if (empty($apiKey)) {
            error_log('B20MAIL_API_KEY não configurada');
            return false;
        }

        $mailFrom = trim($_ENV['MAIL_FROM_ADDRESS'] ?? getenv('MAIL_FROM_ADDRESS') ?? '', '"\'');
        
        $payload = [
            'from'      => $mailFrom ? $mailFrom : 'Sua Empresa <[email protected]>',
            'to'        => $to,
            'subject'   => $subject,
            'type'      => $type,
            'variables' => array_merge($variables, ['email' => $to])
        ];

        // Tenta carregar o template HTML da pasta local. Se não achar, delega pro template global da B20Mail.
        $templateFile = __DIR__ . '/views/emails/' . $templateName . '.html';
        if (file_exists($templateFile)) {
            $payload['html'] = file_get_contents($templateFile);
        } else {
            $payload['template'] = $templateName;
        }

        $apiUrl = trim($_ENV['B20MAIL_API_URL'] ?? getenv('B20MAIL_API_URL') ?? '', '"\'');
        $apiUrl = rtrim($apiUrl ?: 'https://api.b20mail.com', '/');
        
        $ch = curl_init($apiUrl . '/send-email');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST           => true,
            CURLOPT_HTTPHEADER     => [
                'x-api-key: ' . $apiKey,
                'Content-Type: application/json'
            ],
            CURLOPT_POSTFIELDS     => json_encode($payload)
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 200 && $httpCode < 300) {
            return true;
        }

        error_log('B20Mail Erro (HTTP ' . $httpCode . '): ' . $response);
        return false;
    }
}

EXEMPLOS DE INTEGRAÇÃO BÁSICA

PHP / cURL

<?php
$ch = curl_init('https://api.b20mail.com/send-email');
$payload = json_encode([
    'from'      => 'Sua Empresa <[email protected]>',
    'to'        => '[email protected]',
    'subject'   => 'Bem-vindo!',
    'template'  => 'welcome',
    'type'      => 'transactional',
    'variables' => ['name' => 'João', 'link' => 'https://seusistema.com/comecar'],
]);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'x-api-key: SUA_CHAVE_AQUI',
        'Content-Type: application/json',
    ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript / Fetch

async function sendEmail() {
    const response = await fetch('https://api.b20mail.com/send-email', {
      method: 'POST',
      headers: {
        'x-api-key':    'SUA_CHAVE_AQUI',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        from:      'Sua Empresa <[email protected]>',
        to:        '[email protected]',
        subject:   'Bem-vindo!',
        template:  'welcome',
        type:      'transactional',
        variables: { name: 'João', link: 'https://seusistema.com/comecar' },
      }),
    });
    const data = await response.json();
}

Python / requests

import requests

payload = {
    "from":      "Sua Empresa <[email protected]>",
    "to":        "[email protected]",
    "subject":   "Bem-vindo!",
    "template":  "welcome",
    "type":      "transactional",
    "variables": {"name": "João", "link": "https://seusistema.com/comecar"},
}

response = requests.post(
    "https://api.b20mail.com/send-email",
    headers={
        "x-api-key":    "SUA_CHAVE_AQUI",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = response.json()

GERAR API KEY

As API Keys são gerenciadas diretamente pelo Painel Administrativo. Acesse a aba API KEYS no dashboard para:

WEBHOOKS

A B20Mail pode notificar seu sistema em tempo real quando um e-mail sofre bounce (rejeição) ou complaint (spam). Basta cadastrar um endpoint HTTPS no painel ou via API.

Eventos Disponíveis

Formato do Payload

Todos os webhooks são enviados como POST com body JSON:

{
  "event":     "email.bounced",
  "timestamp": "2026-06-29T21:00:00Z",
  "data": {
    "message_id":     "0100018ff123abc-abcd-1234",
    "request_id":     "a1b2c3d4e5f6-123456",
    "recipient":      "[email protected]",
    "subject":        "Bem-vindo!",
    "type":           "Permanent",
    "diagnostic":     "Bounce: 550 5.1.1 User unknown",
    "original_event": "Bounce"
  }
}

Verificação de Assinatura (HMAC-SHA256)

Cada webhook inclui headers de assinatura para garantir autenticidade:

Exemplos de Handler

PHP

<?php
$secret    = 'whsec_seu_secret_aqui';
$payload   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_B20MAIL_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_B20MAIL_SIGNATURE'] ?? '';

// Validar assinatura
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    die('Assinatura inválida');
}

$data  = json_decode($payload, true);
$event = $data['event'] ?? '';

match($event) {
    'email.bounced'    => handleBounce($data['data']),
    'email.complained' => handleComplaint($data['data']),
    default            => null,
};

http_response_code(200);
echo 'OK';

Node.js / Express

const crypto = require('crypto');

app.post('/webhook/b20mail', (req, res) => {
    const secret    = process.env.B20MAIL_WEBHOOK_SECRET;
    const timestamp = req.headers['x-b20mail-timestamp'];
    const signature = req.headers['x-b20mail-signature'];
    const payload   = JSON.stringify(req.body);

    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(timestamp + '.' + payload)
        .digest('hex');

    if (expected !== signature) return res.status(401).send('Invalid');

    const { event, data } = req.body;
    console.log(`Evento: ${event}`, data);
    res.status(200).send('OK');
});

Python / Flask

import hmac, hashlib, json
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook/b20mail', methods=['POST'])
def webhook():
    secret    = "whsec_seu_secret".encode()
    payload   = request.get_data(as_text=True)
    timestamp = request.headers.get('X-B20Mail-Timestamp', '')
    signature = request.headers.get('X-B20Mail-Signature', '')

    expected = 'sha256=' + hmac.new(
        secret, (timestamp + '.' + payload).encode(), hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return 'Invalid', 401

    data = json.loads(payload)
    print(f"Evento: {data['event']}", data['data'])
    return 'OK', 200

Como Cadastrar seu Endpoint

CÓDIGOS DE ERRO