Desenvolvedores

API do AraraSend

API REST para integrar contatos, listas, campanhas e envio de e-mail ao seu sistema. Base: https://ararasend.com/api/v1

Autenticação

Toda requisição usa uma chave de API no header. Crie e gerencie suas chaves no painel, em Painel → API. A chave aparece uma única vez na criação.

Authorization: Bearer ask_live_sua_chave_aqui

Escopos (permissões)

Cada chave tem escopos — marque só o necessário (princípio do menor privilégio):

read — consultar (GET) contatos, campanhas, eventos.
write — criar/editar/remover contatos, listas, tags, campanhas.
send — disparar campanhas e e-mails transacionais.

Sem o escopo exigido pela rota, a resposta é 403 forbidden. Chave sem nenhum escopo = acesso total (compatibilidade).

A chave é presa ao domínio

Ao criar a chave você marca de quais domínios ela pode enviar. Uma chave restrita ao domínio de um sistema não manda e-mail em nome dos seus outros domínios — se ela vazar, o estrago para no projeto que a usava.

GET /v1/domains devolve só o que aquela chave alcança — use para montar o seletor de remetente.
Remetente fora da chave → 400 na API, 550 no SMTP.
Chave criada sem escolher domínio vale para todos os da conta. Funciona, mas evite.

Limites & respostas

Rate-limit: 120 requisições/min por chave (headers RateLimit-Limit/RateLimit-Remaining; 429 ao exceder).
Sucesso: { "data": … }. Erro: { "error": { "type": …, "message": … } }.
Envio: o domínio do remetente precisa pertencer ao seu workspace, e a conta precisa estar com e-mail verificado e dentro do limite de envios do plano.

Idempotência

Retentar um envio que já saiu faz o destinatário receber duas vezes. Mande o header Idempotency-Key e a repetição recebe a mesma resposta, sem reenviar.

Idempotency-Key: pedido-1234-confirmacao

Vale por 24 horas e é isolada por chave de API.
A resposta traz Idempotency-Status: stored, replayed, off ou unavailable.
Chamada recusada antes de enviar (validação, cota) não queima a chave — corrija e reenvie.

Endpoints

Método	Rota	Escopo	O que faz
GET	/v1/contacts	`read`	Lista contatos (paginado: ?limit&offset&status&email)
POST	/v1/contacts	`write`	Cria um contato
GET	/v1/contacts/:id	`read`	Detalha um contato
PATCH	/v1/contacts/:id	`write`	Atualiza um contato
DELETE	/v1/contacts/:id	`write`	Remove um contato
GET	/v1/domains	`read`	Lista os domínios que a chave pode usar como remetente
GET	/v1/tags	`read`	Lista tags
POST	/v1/tags	`write`	Cria uma tag
GET	/v1/audiences	`read`	Lista públicos (listas)
POST	/v1/audiences	`write`	Cria um público
POST	/v1/audiences/:id/contacts	`write`	Adiciona contatos a um público
POST	/v1/emails	`send`	Envia um e-mail transacional (anexos, cc/bcc, idempotência)
GET	/v1/campaigns	`read`	Lista campanhas
POST	/v1/campaigns	`write`	Cria uma campanha (rascunho)
GET	/v1/campaigns/:id	`read`	Detalha uma campanha + métricas
PATCH	/v1/campaigns/:id	`write`	Edita a campanha e agenda o envio (scheduled_at)
DELETE	/v1/campaigns/:id	`write`	Exclui uma campanha (rascunho ou agendada)
POST	/v1/campaigns/:id/send	`send`	Dispara o envio de uma campanha
GET	/v1/events	`read`	Eventos: entregas, aberturas, cliques, bounces (filtra por to e message_id)

Exemplos

Criar um contato

curl https://ararasend.com/api/v1/contacts \
  -H "Authorization: Bearer ask_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "cliente@exemplo.com", "first_name": "Ana", "status": "subscribed" }'

Enviar um e-mail transacional

curl https://ararasend.com/api/v1/emails \
  -H "Authorization: Bearer ask_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "ola@seudominio.com", "name": "Sua Marca" },
    "to": "cliente@exemplo.com",
    "subject": "Bem-vindo!",
    "html": "<h1>Olá 👋</h1>",
    "reply_to": "suporte@seudominio.com",
    "tags": { "pedido": "1234" },
    "attachments": [
      { "filename": "nota.pdf", "content": "<base64>", "content_type": "application/pdf" }
    ]
  }'

Aceita ainda cc/bcc (com um único destinatário em to) e headers próprios com prefixo X-. Até 10 anexos, 25 MB no total.

Ler eventos de uma campanha

curl "https://ararasend.com/api/v1/events?campaign_id=CID&type=open" \
  -H "Authorization: Bearer ask_live_..."

Pronto para integrar?

Criar minha chave de API →