API v3 quickstart: do zero ao seu primeiro envio

Se você quer operar a arrobaMail a partir do seu próprio sistema — cadastrar contatos, disparar campanhas, ler estatísticas —, o caminho é a API REST v3: JSON sobre HTTP, autenticação com JWT, e nenhum SDK obrigatório. Este guia é o atalho: em três requisições você sai do zero e chega ao seu primeiro envio.

1. O plano: três requisições

Toda a integração básica se resume a três chamadas HTTP: você se autentica (e guarda um token), cadastra um contato numa lista e envia. Com isso, já está operando. Depois você pode incorporar consultas de estatísticas, segmentações e muito mais — mas o núcleo é esse.

A URL base da API é https://envios.arrobamail.com/v3/api/ (troque envios pelo servidor atribuído à sua conta).

2. Autenticar: o token JWT

Tudo começa pedindo um token — um passe temporário que autoriza suas chamadas:

POST /auth/getToken
Content-Type: application/json

{ "username": "seu_usuario", "pass": "sua_senha", "rememberMe": true, "locale": "pt" }

Você recebe um token. A partir daqui, toda chamada protegida precisa levá-lo no header:

Authorization: Bearer {token}

Atenção: o campo é pass, não password. E com rememberMe: true o token dura até 365 dias (ótimo para produção); com false, é curto — ideal para testes.

3. Deixe prontos o remetente e a lista

Antes de enviar, duas coisas precisam já existir na sua conta:

• Um remetente verificado. Para enviar, o from precisa estar certificado com SPF/DKIM. Se não estiver, a API rejeita o envio. (Você verifica uma única vez — veja em verifique seu remetente.)
• Uma lista. Com GET /lists você obtém suas listas e seus IDs. Anote o ID da lista de destino — é uma string criptografada, não um número.

4. Cadastrar um contato

Você adiciona (ou confirma) o assinante que vai receber o envio, dentro dessa lista:

POST /lists/:id/subscribers
Authorization: Bearer {token}

{ "email": "[email protected]", "name": "Cliente" }

Atenção: o contato precisa ficar com o status Ativo. Se sua lista usa double opt-in e ele fica como Pendente, não vai receber envios nem disparar automações.

5. Enviar

A chamada que coloca o envio na fila. Com o nome, o assunto, o HTML, o remetente e a lista:

POST /campaigns
Authorization: Bearer {token}

{ "campname": "Meu_primeiro_envio", "asunto": "Olá, isso vem da API",
  "html": "<h1>Funciona</h1>", "fromname": "Sua Empresa",
  "frommail": "[email protected]", "listid": ["SEU_LIST_ID"],
  "tracklinks": 1, "trackreads": 1 }

Você recebe um encid (o identificador da campanha). Guarde-o para consultar depois.

6. Conferir o resultado e seguir na sua linguagem

Com o encid, você consulta como foi:

GET /campaigns/{encid}/stats/subscriber-actions
Authorization: Bearer {token}

Isso mostra se o e-mail foi entregue, se foi aberto e se houve cliques. E pronto: você já integrou a arrobaMail ao seu sistema.

Este guia usou pseudo-HTTP para deixar o fluxo mais claro. O código real, pronto para copiar em curl, Node, PHP ou Python, está no quickstart da API (com abas por linguagem), e o detalhe de cada endpoint — todos os parâmetros e respostas — na referência.

Erros comuns para evitar

• Mandar password em vez de pass. O campo da senha é pass. É o tropeço número um.
• Remetente sem verificar. Se o frommail não estiver certificado, o envio é rejeitado. Verifique antes.
• Tratar o listid como número. É uma string criptografada. Passe exatamente como GET /lists devolve.
• Esquecer o espaço no header. Precisa estar exatamente assim: Authorization: Bearer {token}, com o espaço depois de Bearer.

Próximos passos

1. Pegue o código na sua linguagem no quickstart da API.
2. Aprofunde-se em cada endpoint na referência.
3. Para enviar e-mails individuais disparados por evento, veja enviar e-mails transacionais.