REST API · v1

Um token. Todos os endpoints.

Uma API HTTP limpa e orientada a recursos para campanhas, listas, inscritos, automações, servidores de envio e cobrança de clientes. Autentique com um único token, consulte JSON, entregue em minutos. A mesma API que os plugins usam é a mesma API que os clientes externos usam — sem endpoints de segunda classe.

Início rápido em 4 passos ↓ Catálogo de endpoints

O que você pode construir

Frontend SaaS App mobile Sincronização com CRM Gatilhos de automação Dashboards de revendedor
REQUEST POST /api/v1/campaigns HEADERS Authorization: Bearer ACELLE_TOKEN Content-Type: application/json BODY { "list_uid": "a3b9..." "name": "Welcome" "subject": "Hi friend" "from_name": "Acme" "from_email": "hi@..." "track_open": true "html": "<h1>…" } HTTPS your.acelle.com RESPONSE 200 OK { "campaign": { "uid": "abc123" "name": "Welcome" "subject": "Hi friend" "status": "ready" "track_open": true "created_at": "2026-05-06T…" "links": { "self": "/api/v1…" } } }

POR QUE ESTA API

Sem surpresas. Sem endpoints de segunda classe.
A mesma API que seus plugins usam.

Autenticada por token

Cada requisição carrega um único token bearer. Gerado por usuário em Profile → API token. Passe via cabeçalho Authorization: Bearer ou por query string ?api_token=. Revogue e rotacione a qualquer momento.

Orientada a recursos

Cada conceito é um recurso com verbos previsíveis. GET /lists retorna a coleção, POST /lists cria uma, PATCH /lists/:uid atualiza, DELETE /lists/:uid remove. Sub-recursos se aninham naturalmente: /lists/:uid/subscribers.

A mesma que os plugins usam

Não existe divisão interna vs. externa. Os endpoints que a própria UI da AcelleMail chama, os endpoints que seu plugin estende e os endpoints que seu cliente externo lê — idênticos. Veja o SDK de plugins →

Endpoint auto-hospedado

A URL base é o seu próprio servidor — https://your-acelle.example.com/api/v1/. Sem proxy de fornecedor, sem rate limit compartilhado, sem taxa por requisição. O throughput é o que seu hardware permitir.

INÍCIO RÁPIDO

Do zero à primeira resposta em quatro passos.

Cada instalação da AcelleMail hospeda sua própria API em /api/v1/. Substitua your-acelle.example.com pelo hostname da sua instalação.

STEP 1

Gere um token

Faça login na sua instalação AcelleMail. Abra o menu do seu perfil e clique em API token. Copie o valor — ele é único por usuário e está vinculado às permissões desse usuário.

# In your shell:
$ export ACELLE_TOKEN=paste-your-token-here
$ export ACELLE_BASE=https://your-acelle.example.com
STEP 2

Verifique o token

Chame /me. Se o token é válido, você recebe seu registro de usuário de volta. Se não, você recebe um 401 — confira o token e a URL base.

$ curl $ACELLE_BASE/api/v1/me \
    -H "Authorization: Bearer $ACELLE_TOKEN"

{ "id": 1, "email": "you@…", "uid": "…" }
STEP 3

Crie uma lista

Recursos são criados com POST. Os campos obrigatórios no body para uma lista de email são name, from_email, from_name, subject, além de um bloco de contato.

$ curl -X POST $ACELLE_BASE/api/v1/lists \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name":       "Newsletter",
      "from_name":  "Acme",
      "from_email": "hi@acme.com",
      "subject":    "Welcome"
    }'
STEP 4

Adicione um inscrito

Use o UID da lista do passo 3. Campos personalizados são passados como params em maiúsculas (FIRST_NAME, LAST_NAME, …) correspondendo à configuração de campos da sua lista.

$ curl -X POST $ACELLE_BASE/api/v1/subscribers \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -d list_uid=$LIST_UID \
    -d EMAIL=alice@example.com \
    -d FIRST_NAME=Alice \
    -d tag=newsletter,beta

RECURSOS

Oito recursos. Mais de quarenta endpoints. Todos os verbos que você esperaria.

Todos os endpoints abaixo são namespaced sob /api/v1/ e exigem autenticação por token auth:api, exceto quando indicado. Ações de ciclo de vida (run, pause, resume) são expostas como sub-rotas POST. Downloads de logs entregam o CSV subjacente em stream.

Autenticação

Todos os endpoints autenticados aceitam o token via cabeçalho Authorization: Bearer (preferido) ou pelo parâmetro de query ?api_token= (legado). Use POST /user/login para trocar email/senha por um token novo a partir de um cliente programático.

POST/user/loginTroque email + senha por um token de API. Endpoint público.
GET/meRetorna o registro do usuário autenticado. Use isto para verificar um token.
POST/login-tokenGere uma URL de login one-time que o usuário pode clicar para chegar já autenticado.

Listas

Listas de email são o contêiner primário de inscritos. Cada lista vem com uma identidade de remetente padrão, campos personalizados e ajustes de double-opt-in / email de boas-vindas. Campos personalizados são adicionados pela sub-rota add-field.

GET/listsÍndice paginado de listas pertencentes ao usuário do token.
POST/listsCrie uma nova lista. Obrigatório: name, from_email, from_name, subject + bloco de contato.
GET/lists/:uidBusque uma única lista com seus campos e estatísticas.
PATCH/lists/:uidAtualize metadados da lista, a identidade de remetente ou os ajustes de opt-in.
POST/lists/:uid/add-fieldAdicione um campo personalizado. O tipo é text, number ou datetime.
DELETE/lists/:uidApague permanentemente uma lista e todos os seus inscritos.

Inscritos

Inscritos pertencem a uma lista e carregam valores de campos personalizados, tags e um histórico de aberturas/cliques. O status é um dos seguintes: subscribed, unsubscribed ou unconfirmed. Operações de tag são aditivas e idempotentes.

GET/subscribers?list_uid=…Índice paginado. Filtre com open=yes|no, click=yes|no.
POST/subscribersCrie. Obrigatório: list_uid, EMAIL. Campos personalizados como params em maiúsculas.
GET/subscribers/:idBusque um único inscrito por id ou email.
GET/subscribers/email/:emailEncontre todas as listas que têm um inscrito com este email.
PATCH/subscribers/:idAtualize campos, tags ou status.
POST/subscribers/:id/add-tagAdicione tags separadas por vírgula.
POST/subscribers/:id/remove-tagRemova tags separadas por vírgula.
PATCH/lists/:list_uid/subscribers/:id/subscribeMarque como subscribed.
PATCH/lists/:list_uid/subscribers/:id/unsubscribeMarque como unsubscribed.
PATCH/lists/:list_uid/subscribers/email/:email/unsubscribeDescadastre por email quando você não tem o id.
DELETE/subscribers/:idHard delete da lista.

Campanhas

Campanhas são a unidade de envio. Crie uma com conteúdo HTML + flags de rastreamento, transicione por run / pause / resume e depois baixe logs de rastreamento, abertura, clique, bounce, feedback e descadastro como CSV.

GET/campaignsÍndice paginado. Passe per_page, page.
POST/campaignsCrie. Obrigatório: list_uid, name, subject, from_*, html.
GET/campaigns/:uidBusque uma única campanha com estatísticas.
PATCH/campaigns/:uidAtualize conteúdo, assunto ou flags de rastreamento.
POST/campaigns/:uid/runColoque a campanha na fila para entrega.
POST/campaigns/:uid/pausePause uma campanha em andamento.
POST/campaigns/:uid/resumeRetome uma campanha pausada.
GET/campaigns/:uid/tracking-log/downloadFaça stream do CSV de rastreamento.
GET/campaigns/:uid/{open,click,bounce,feedback,unsubscribe}-log/downloadFaça stream do CSV por evento (uma rota por tipo de evento).
DELETE/campaigns/:uidApague uma campanha (somente quando não estiver em andamento).

Automações

Automações são fluxos visuais de gatilhos, condições e ações. A API expõe a visão de leitura mais duas formas de disparar fluxos a partir de sistemas externos: execute para rodar uma automação inteira ou api/call para acionar um nó "API call" no meio do fluxo.

GET/automationsÍndice de automações que o usuário do token possui.
POST/automations/:uid/executeDispare uma automação para um inscrito. Útil para fluxos transacionais.
POST/automations/:uid/api/callAcione um nó de gatilho "API call" no meio do fluxo com payload customizado.

Servidores de envio

Servidores de envio são os transportes configuráveis (SMTP, Amazon SES, SendGrid, Mailgun, Postmark, drivers personalizados vindos de plugins). Gerencie-os programaticamente ao provisionar novos tenants ou rotacionar credenciais.

GET/sending_serversÍndice dos servidores de envio configurados.
POST/sending_serversCrie um novo servidor de envio. Configuração específica do driver em settings.
GET/sending_servers/:uidBusque um único servidor de envio.
PATCH/sending_servers/:uidAtualize ajustes ou rotacione credenciais.
DELETE/sending_servers/:uidRemova um servidor de envio (campanhas que o referenciam precisam ser re-roteadas antes).

Adicionar um novo transporte (Postal MTA, API HTTP personalizada, …) é um REGISTRY hook — entregue como plugin em vez de patchear o core.

Clientes ADMIN

Endpoints de cliente são restritos a tokens de admin. Use-os para provisionar contas de tenant, gerenciar assinaturas, trocar de plano ou gerar URLs de login one-time para suporte/personificação.

GET/customersÍndice paginado de todos os clientes.
POST/customersCrie um novo cliente + conta de usuário.
GET/customers/by-email/:emailProcure um cliente por email.
PATCH/customers/:uidAtualize o perfil / contato / quota do cliente.
PATCH/customers/:uid/{enable,disable}Suspenda ou reative o acesso sem apagar dados.
POST/customers/:uid/change-plan/:plan_uidTroque um cliente para um plano diferente (cobranças, prorrateamento, renovação de assinatura).
POST/customers/:uid/assign-plan/:plan_uidAtribua um plano sem fluxo de cobrança (override de admin).
POST/customers/:uid/subscription/updateAtualize os parâmetros de uma assinatura ativa.
POST/login-tokenGere uma URL de login one-time para o cliente-alvo.

Assinaturas ADMIN

Assinaturas ligam um cliente a um plano + cadência de cobrança. Use estes endpoints ao integrar com sistemas externos de cobrança ou ao auditar receita recorrente.

GET/subscriptionsÍndice de todas as assinaturas ativas.
POST/subscriptionsCrie um registro de assinatura (tipicamente acionado pelo webhook do seu gateway).
GET/subscriptions/:uidBusque uma única assinatura com seu histórico de renovações.
PATCH/subscriptions/:uidAjuste quota, cadência ou data de término.

Arquivos

Faça upload de imagens e outros assets para uso no conteúdo de campanha. O endpoint aceita multipart/form-data e retorna uma URL pública que você pode referenciar no body HTML.

POST/file/uploadFaça upload de um arquivo. Retorna { "url": "..." }.

Plugins & upgrades ADMIN

Instale plugins programaticamente a partir de uma URL de download, rode upgrades remotos do core em um fluxo de requisição em dois passos (para que o passo 2 caia em um worker PHP novo) ou atualize a licença. Útil para operadores de frota que gerenciam muitos tenants AcelleMail.

POST/plugins/installInstale um plugin a partir de uma URL de download.
POST/upgrade/runInicie um upgrade remoto do core (baixa + extrai).
POST/upgrade/run-fileAplique um único passo de migração.
POST/upgrade/finalizeFinalize um upgrade. Deve ser chamado como uma requisição nova depois de run.
POST/license/refreshAtualize as informações de licença do CodeCanyon (espelha Admin → License).

WEBHOOKS

Empurre eventos para fora, em vez de fazer polling deles.

A AcelleMail inclui duas superfícies de webhook. Lifecycle webhooks disparam em transições de cliente + assinatura + automação e são configurados globalmente. Pings de rastreamento por destinatário disparam em aberturas / cliques / descadastros e são configurados por campanha. Ambos refazem tentativas em caso de falha com backoff exponencial.

Lifecycle webhooks

Transições de cliente + assinatura

Configurados uma vez em Admin → Settings → Webhooks. Cada webhook é um nome + evento + configuração HTTP de saída (URL, método, headers, template de body). Seis eventos vêm no core:

new_customer — params: customer_id
new_subscription — customer_id, plan_id
change_plan — customer_id, old_plan_id, new_plan_id
cancel_subscription — customer_id, plan_id
terminate_subscription — customer_id, plan_id
automation_webhook — automation_id (dispara a partir de nós API call)

A política de retry é por-webhook: retry_times configurável (padrão 2) e retry_after_seconds (padrão 900). Entregas falhas são logadas, refeitas e expostas no log admin de webhook.

Plugins podem registrar eventos adicionais via o padrão EVENT hook — acelle/ai, por exemplo, dispara ai_task_completed a partir dos seus próprios listeners customizados.

Rastreamento por destinatário

Aberturas, cliques, descadastros

Configurados por campanha ou por template de email em Tracking → Webhooks. Três tipos de evento disparam à medida que o destinatário interage com a mensagem:

open — destinatário abriu o email (pixel de rastreamento)
click — destinatário clicou em um link rastreado
unsubscribe — destinatário clicou no link de descadastro

Cada ping carrega o uid da campanha, o email do inscrito e a URL do clique (para eventos click). Configure quantos webhooks de rastreamento precisar por campanha — útil para espelhamento paralelo para analytics + CRM + data warehouse.

Eventos no nível do servidor de envio (bounce, complaint, delivery) fluem pelo stack interno de listeners App\SendingServers\Webhooks\* — expostos nos endpoints de log de campanha em vez de como webhooks de saída. Baixar CSVs de log →

Exemplo: payload de new_subscription

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: new_subscription
X-AcelleMail-Signature: sha256=…

{
  "event":       "new_subscription",
  "customer_id": 1234,
  "plan_id":     "extended-monthly",
  "fired_at":    "2026-05-06T12:34:56Z"
}

Exemplo: payload de rastreamento click

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: click

{
  "event":         "click",
  "campaign_uid":  "abc123",
  "subscriber":    "alice@example.com",
  "url":           "https://acme.com/promo",
  "clicked_at":    "2026-05-06T12:34:56Z"
}

RESPOSTAS & ERROS

JSON previsível. Status codes convencionais.

Toda resposta de sucesso é JSON. Toda resposta de falha é JSON, com um message de nível raiz e um mapa errors para falhas de validação. Os status codes seguem a convenção REST — você pode bifurcar seu cliente pelo código sozinho.

Code Quando você verá
200 OKLeitura ou atualização bem-sucedida.
201 CreatedCriação bem-sucedida.
401 UnauthorizedToken ausente ou inválido.
403 ForbiddenToken válido, mas o recurso não é seu / não é admin.
404 Not FoundO UID não existe.
422 UnprocessableErro de validação. Cheque o mapa errors no body.
500 ServerBug do lado do servidor. Cheque storage/logs/laravel.log.

Erro de validação (422)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "from_email": [
      "The from_email field is required."
    ],
    "subject": [
      "The subject must be at most 998 characters."
    ]
  }
}

Falha de autenticação (401)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "message": "Unauthenticated." }

Paginação

Endpoints de índice aceitam per_page (padrão 10–25 dependendo do recurso) e page. As respostas incluem o formato padrão do paginator do Laravel: data[], links, meta.current_page, meta.total.

Rate limits

Rate limiting é decisão sua — configure na sua instalação Laravel via RouteServiceProvider. Os builds padrão vêm sem throttle de API, já que você está chamando seu próprio servidor. Adicione throttle:60,1 se quiser.

Versionamento

A versão major atual é v1. Novos endpoints são adicionados livremente; mudanças com quebra em endpoints existentes seriam entregues como v2 ao lado da v1. Trave seu cliente em /api/v1/ e estará estável.

CLIENTES

Qualquer cliente HTTP. Sem SDK proprietário.

Não há SDK da AcelleMail para instalar. A API fala JSON sobre HTTP — use o cliente que sua stack já tem. Três dos mais comuns na prática:

curl · one-liners

curl $ACELLE_BASE/api/v1/lists \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  | jq '.data[].name'

Cliente HTTP do Laravel

$resp = Http::withToken($token)
    ->baseUrl($base.'/api/v1')
    ->post('/subscribers', [
        'list_uid' => $listUid,
        'EMAIL'    => $email,
    ]);

return $resp->json();

fetch no navegador / Node

const r = await fetch(
  `${base}/api/v1/campaigns/${uid}/run`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);
const data = await r.json();

Está construindo um SDK open-source? Mande um email — vamos linkar a partir desta página.

REFERÊNCIA CANÔNICA

A referência completa e executável da API.

Cada parâmetro. Cada forma de retorno. Cada exemplo curl funcional. Hospedada na instalação demo canônica — o mesmo código que sua instalação roda.

api.acellemail.com

Substitua api.acellemail.com pelo hostname da sua própria instalação ao chamar.

RECURSOS & COMUNIDADE

Construa com a API, entregue como plugin, pergunte quando ficar travado.

Para desenvolvedores

SDK de plugins, sistema de Hooks, plugin Hello World em 5 minutos e 14 superfícies de extensão com exemplos reais de produção.

/for/developers →

Referência completa da API

Referência ao vivo e executável para cada endpoint — parâmetros, retornos, exemplos curl funcionais.

api.acellemail.com →

Base de conhecimento

Configuração, entregabilidade, configuração de servidor de envio, resolução de problemas, guias de plugin, cobrança.

acellemail.com/kb →

Travado? Mande um email

Contrato de endpoint, payload de webhook ou dúvida de auth. Resposta típica em 24 horas.

support{{ landing_brand('domain') }} →

COMECE A CONSTRUIR

Rode a AcelleMail. Pegue um token. Faça uma chamada.

Licença com pagamento único. Código-fonte completo. Endpoint auto-hospedado. A API está incluída — sem add-on, sem rate plan.

SDK de plugins →

Rode seu email marketing no seu próprio servidor, nos seus próprios termos

Junte-se a milhares de empresas que assumiram o controle do seu email marketing com código-fonte completo, sem mensalidades e envios ilimitados. Licença de pagamento único de $80, atualizações vitalícias.

Get the AcelleMail newsletter

Monthly issue with new releases, deliverability tips, and self-hosting playbooks. No spam.