Do domínio ao primeiro envio, sem atrito.

# Chave gerada no painel — aparece uma única vez
DEXMAIL_API_KEY="dx_sua_chave_aqui"   # nunca no cliente

# É só isso. O SDK oficial já aponta para https://api.dexmail.com.br/api/v1 —
# não há URL para configurar. Defina DEXMAIL_API_URL apenas se quiser apontar
# a outro ambiente (dev/staging).

import { DexMail } from "@dexmail/node";

// Lê DEXMAIL_API_KEY do ambiente. A URL da API já vem embutida no SDK.
const dexmail = new DexMail();

const { id, status } = await dexmail.emails.send({
  from: "Equipe <noreply@mail.suaempresa.com.br>",
  to: "cliente@exemplo.com",        // ou ["a@x.com", "b@x.com"] (até 50)
  subject: "Bem-vindo a bordo",
  html: "<h1>Olá 👋</h1><p>Seu primeiro e-mail transacional.</p>",
  // opcionais: text, reply_to, cc, bcc, headers,
  //   tags: [{ name: "fluxo", value: "onboarding" }],
  //   attachments: [{ filename: "guia.pdf", content: "<base64>" }],
});

// Envio reentrante (evita duplicar em retry): 2º arg com idempotencyKey
// await dexmail.emails.send({ ... }, { idempotencyKey: "pedido-123" });

console.log(id, status); // "ckq…"  "queued"

Integre o envio de e-mails transacionais deste projeto com o DEXMail (https://dexmail.com.br).
Antes de escrever código, leia o repositório e siga as convenções que já existem nele
(linguagem, gerenciador de pacotes, estrutura de pastas, padrão de log e de erro).

O QUE É
Serviço de e-mail transacional com API REST. Base: https://api.dexmail.com.br/api/v1
Autenticação: header "Authorization: Bearer <chave dx_...>" — segredo de servidor.
SDK oficial Node/TypeScript: @dexmail/node (ESM + CJS, zero dependências, retry em 429/5xx).
Em outras linguagens, chame a API REST com o cliente HTTP que o projeto já usa.

CONTRATO (não invente rotas nem campos)
  POST   /emails       -> 202 { "id": "...", "status": "queued" }   (envio assíncrono)
  GET    /emails       -> lista paginada por cursor (status, limit, cursor)
  GET    /emails/:id   -> status + timeline do e-mail
  POST/GET /webhooks · DELETE /webhooks/:id

Corpo do POST /emails:
  from      obrigatório   "Nome <endereco@dominio-verificado>"
  to        obrigatório   string ou array (to + cc + bcc somam no máximo 50)
  subject   obrigatório
  html e/ou text          pelo menos um dos dois
  opcionais: reply_to, cc, bcc, headers, tags [{ name, value }],
             attachments [{ filename, content (base64), content_type }] (até 20, 40 MB no total)
  header "Idempotency-Key": torna o envio reentrante por 24h (mesma chave + mesmo corpo
  devolve o e-mail original; corpo diferente responde 409).

Erros: 401 authentication_error · 403 permission_error (domínio do from não verificado) ·
404 not_found · 409 conflito de idempotência · 422 invalid_request (traz "fields" com o erro
por campo) · 429 rate_limit (100 req/min por key e por IP; respeite Retry-After).

PASSOS
1. Instale @dexmail/node com o gerenciador de pacotes já usado no repositório.
2. Crie UM módulo de e-mail (ex.: lib/email.ts) que instancie o cliente uma vez e exporte
   uma função por caso de uso (boas-vindas, recuperação de senha, recibo...). Nenhum outro
   arquivo deve falar com a API diretamente.
3. Configuração por ambiente, validada na inicialização (falhe cedo se faltar):
     DEXMAIL_API_KEY  chave dx_... (somente servidor)
     EMAIL_FROM       remetente em domínio verificado
   Acrescente as duas ao .env.example. Nunca comite a chave real. Não configure baseUrl:
   o SDK já aponta para a API de produção.
4. Envie sempre a partir do servidor (route handler, server action, controller, job).
   Nunca do cliente, nunca em variável pública (NEXT_PUBLIC_, VITE_ e afins).
5. Use idempotencyKey em todo envio que possa ser reexecutado por retry, com um id estável
   do domínio ("welcome:" + userId, "invoice:" + invoiceId...).
6. Trate erros com as classes do SDK (InvalidRequestError, PermissionError, RateLimitError,
   DexMailError) e registre err.type e err.requestId. Falha de e-mail não pode derrubar o
   fluxo principal do usuário.
7. Guarde o id retornado junto do registro de domínio (usuário, pedido...) para auditar
   depois via GET /emails/:id.
8. Se houver testes, mocke o módulo de e-mail — nunca chame a API real em teste.

FORMATO ESPERADO (TypeScript; adapte à stack do projeto)
    import { DexMail, DexMailError } from "@dexmail/node";

    const dexmail = new DexMail(); // lê DEXMAIL_API_KEY do ambiente

    export async function sendWelcomeEmail(to: string, name: string) {
      try {
        return await dexmail.emails.send(
          {
            from: process.env.EMAIL_FROM,
            to,
            subject: "Bem-vindo!",
            html: "<p>Olá, " + name + "</p>",
          },
          { idempotencyKey: "welcome:" + to },
        );
      } catch (err) {
        if (err instanceof DexMailError) {
          logger.error({ type: err.type, requestId: err.requestId }, "falha no envio");
        }
        throw err;
      }
    }

SE O PROJETO JÁ USA SMTP
Não reescreva: aponte o transporte existente (Nodemailer, ActionMailer, PHPMailer,
WordPress...) para host smtp.dexmail.com.br, porta 465 (TLS) ou 587 (STARTTLS),
usuário "dexmail" e senha = a própria API key dx_....

AO TERMINAR
Liste os arquivos criados/alterados, as variáveis de ambiente que preciso definir e como
disparar um envio de teste. Se algo do contrato acima não bater com o código do projeto,
pare e me pergunte em vez de adivinhar.
Referência: https://dexmail.com.br/docs · OpenAPI: https://dexmail.com.br/docs/api

import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: process.env.EMAIL_FROM,
  to: "cliente@exemplo.com",
  subject: "Bem-vindo!",
  html: "<p>Sua conta foi criada.</p>",
});

curl "https://api.dexmail.com.br/api/v1/emails/em_18a2c" \
  -H "Authorization: Bearer $DEXMAIL_API_KEY"

# → { "id": "em_18a2c", "status": "delivered", "to": "cliente@exemplo.com" }

// POST assinado para a sua URL (header DEXMail-Signature)
{
  "type": "email.delivered",
  "email_id": "em_18a2c",
  "created_at": "2026-07-08T13:40:11Z"
}

import express from "express";
import { verifyWebhookSignature, WebhookVerificationError } from "@dexmail/node";

app.post(
  "/webhooks/dexmail",
  express.raw({ type: "application/json" }), // precisa do corpo CRU
  (req, res) => {
    try {
      const event = verifyWebhookSignature(
        req.body,                       // Buffer cru — não reserialize o JSON
        req.header("DEXMail-Signature"),
        process.env.DEXMAIL_WEBHOOK_SECRET!,
      );
      // trate de forma idempotente pelo event.id (entrega é at-least-once)
      console.log(event.type, event.data.email_id);
      res.status(200).end();          // responda 2xx rápido
    } catch (err) {
      if (err instanceof WebhookVerificationError) return res.status(400).end();
      throw err;
    }
  },
);

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.dexmail.com.br",
  port: 465,
  secure: true,
  auth: { user: "dexmail", pass: process.env.DEXMAIL_API_KEY }, // a senha É a API key
});

await transport.sendMail({
  from: "Equipe <noreply@mail.suaempresa.com.br>",
  to: "cliente@exemplo.com",
  subject: "Bem-vindo a bordo",
  html: "<p>Sua conta foi criada.</p>",
});