API para desenvolvedores

Uma única API REST para listas, campanhas, e-mail transacional — e a IA.

Primeiros passos

Todos os planos pagos incluem acesso completo à API REST. Gere uma chave na sua conta, em Conta → Chaves de API, e envie-a em cada requisição:

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/lists

URL base: https://mailflow.top/api/index.php · As respostas são em JSON, com um campo status de valor success ou error. A API não está disponível no plano gratuito.

Recursos principais

A plataforma é compatível com o MailWizz, por isso toda a API principal — listas, assinantes, segmentos, campos personalizados, campanhas, rastreamento, modelos, e-mail transacional, bounces, cancelamentos de inscrição — está documentada de forma interativa (OpenAPI), junto com todos os endpoints do MailFlow desta página, em:

→ Referência interativa da API (OpenAPI)

Os SDKs existentes do MailWizz (por exemplo, o SDK oficial para PHP) funcionam imediatamente — basta apontá-los para a URL base acima.

Endpoints de IA

Os recursos de IA são cidadãos de primeira classe na API. A mesma chave, a mesma autenticação e os mesmos limites de plano e medição de créditos do aplicativo web.

GET /ai/credits

Seu medidor de créditos de IA do mês atual. Os créditos valem por mês de cobrança, e os créditos não utilizados não são acumulados.

{"status":"success","data":{"unlimited":false,"limit":750,"used":112,"remaining":638}}

GET /ai/replies

Classificações do Smart Replies para suas campanhas — alimente seu CRM com quem tem interesse, quem fez uma pergunta e quem reclamou. Filtros: category (interested, question, complaint, unsubscribe_request, auto_reply, out_of_office, bounce, other), campaign_uid, since (YYYY-MM-DD), page, per_page (máx. 50).

curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/ai/replies?category=interested&since=2026-08-01"

{"status":"success","data":{"count":42,"current_page":1,"per_page":20,"total_pages":3,
  "records":[{"from_email":"[email protected]","subject":"RE: your offer",
    "category":"interested","confidence":98,"engine":"embeddings",
    "summary":"...","suggested_reply":"...","date_added":"2026-08-24 18:21:19",
    "campaign_uid":"py794hjqk8a8d"}]}}

GET /ai/tiers

Níveis de engajamento por IA (vip, engaged, passive, at_risk, dormant) por lista — a mesma pontuação que alimenta o piloto automático e a reconquista.

{"status":"success","data":{"records":[
  {"list_uid":"qk661oq7nl8c1","name":"Main list","tiers":{"engaged":1200,"passive":3400,"dormant":900}}]}}

POST /ai/subject-lines

Gere linhas de assunto em qualquer idioma. Corpo: topic (obrigatório), count (1–5, padrão 3), language (opcional). Consome créditos de IA como o editor web.

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"Summer sale for B2B customers","count":3,"language":"Greek"}' \
  https://mailflow.top/api/index.php/ai/subject-lines

{"status":"success","data":{"subjects":["...","...","..."],"credits_remaining":636}}

GET /ai/flows · POST /ai/flows/author · POST /ai/flows/<uid>/enroll · POST /ai/flows/<uid>/status

Criador de fluxos com IA via API: liste seus fluxos com contadores em tempo real; peça à IA que crie um fluxo completo a partir de um objetivo em linguagem simples ({"goal":"...","list_uid":"..."} — retorna um rascunho que você ativa com {"status":"active"}); insira um assinante em um fluxo ({"email":"..."}).

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"When someone replies interested, notify me, wait 2 days, then send a case study"}' \
  https://mailflow.top/api/index.php/ai/flows/author

Crie seu próprio aplicativo com o MailFlow

Tudo o que você faz no aplicativo web pode ser feito pela API, então você pode operar o MailFlow a partir do seu próprio software. Um fluxo típico:

  1. Crie uma lista e adicione contatos: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Encontre novos contatos com o DataStack: POST /datastack/import.
  3. Crie uma campanha você mesmo (POST /campaigns) ou deixe a IA escrevê-la: POST /ai/campaigns.
  4. Revise e agende o rascunho da IA: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Consulte os resultados: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Tarefas longas (redação com IA, leitura de sites, importações do DataStack) são executadas em segundo plano: a chamada responde 202 com um job_id, e GET /ai/jobs/<job_id> informa quando ela terminou.

Análises

Os mesmos números do seu painel e dos relatórios de campanha. As datas estão em UTC; from e to (YYYY-MM-DD) usam por padrão os últimos 30 dias. Os totais da conta são atualizados a cada poucos minutos.

  • GET /analytics/overview — listas, assinantes, campanhas e resultados de envio de um período: enviados, entregues, aberturas, cliques, bounces, reclamações, cancelamentos de inscrição e suas taxas.
  • GET /analytics/timeline — os mesmos resultados por dia (ou por hora com interval=hour), além dos novos assinantes.
  • GET /analytics/campaigns — uma linha por campanha com seus resultados; filtre com status.
  • GET /campaigns/<campaign_uid>/opens e /clicks — quem abriu ou clicou, quando, de onde e em qual dispositivo (unique=1 apenas para os primeiros eventos).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — cliques por link, resultados por país e cidade, por tipo de dispositivo e por hora, além dos relatórios de abuso.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — os relatórios básicos da campanha.
  • GET /lists/<list_uid>/stats — assinantes por status e origem, crescimento diário e as campanhas enviadas para a lista.
curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/analytics/overview?from=2026-09-01&to=2026-09-30"

{"status":"success","data":{"period":{"from":"2026-09-01","to":"2026-09-30","timezone":"UTC"},
  "lists":9,"subscribers":{"total":52040,"confirmed":50102,"unsubscribed":311},
  "campaigns":{"total":24,"sent":20,"draft":4},
  "activity":{"sent":48210,"delivered":47650,"unique_opens":14230,"unique_clicks":2210,
    "bounces":402,"complaints":3,"unsubscribes":95,"open_rate":29.86,"click_rate":4.64}}}

Conta e configuração de envio

  • GET /account · PUT /account — seu perfil, plano, cota de envio e limites; atualize seu nome, telefone ou fuso horário.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — grupos de campanhas.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — listas de supressão (até 10.000 e-mails por chamada).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — sua lista de bloqueio e se um endereço está bloqueado em algum lugar.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — domínios de envio com os registros DKIM, SPF e DMARC que você deve publicar.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — seus próprios domínios de rastreamento de links.
  • GET /delivery-servers · GET /countries — os servidores pelos quais você pode enviar e os países com suas zonas.

Campanhas com IA

Deixe a IA escrever campanhas para você, com ou sem a sua revisão. A IA usa o perfil do seu negócio, escolhe o público e o horário de envio, verifica o e-mail nos filtros de spam e o escreve no idioma de cada assinante.

  • POST /ai/campaigns — diga à IA o que enviar: goal (obrigatório), list_uid (uma lista, auto ou prospects), audience, business, template_uid, follow_up, auto_send.
  • POST /ai/campaigns/prepare — a IA decide o que enviar em seguida (até 3 por dia); hint opcional.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — campanhas com IA, incluindo assuntos, público, horário sugerido e verificação de spam (html=1 inclui o e-mail).
  • POST /ai/campaigns/<run_id>/approve — agende a campanha: when = proposed, now ou custom com send_at; max_send opcional.
  • POST /ai/campaigns/<run_id>/revise (com feedback) · POST /ai/campaigns/<run_id>/discard — peça alterações ou descarte o rascunho.
  • GET /ai/jobs/<job_id> — status de uma tarefa em segundo plano e as campanhas com IA que ela criou.
  • GET|PUT /ai/hands-off — modo totalmente automático: a IA planeja, escreve e envia sem esperar por você ({"enabled":true}).
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Invite our customers to the autumn webinar","list_uid":"auto"}' \
  https://mailflow.top/api/index.php/ai/campaigns

{"status":"success","data":{"job_id":512,"job_status":"queued","check":"/ai/jobs/512"}}

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/ai/jobs/512

{"status":"success","data":{"job_id":512,"type":"autopilot","status":"done","ai_campaigns":[331],"sent":false}}

Perfis de negócio

A IA escreve em nome do seu negócio. Mantenha um perfil por site:

  • GET|POST /ai/businesses — seus negócios; adicione um com website.
  • GET|PUT|DELETE /ai/businesses/<domain> — perfil, remetente (from_name, from_email, reply_to) e dados da empresa (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — deixe a IA ler o site e preencher o perfil; defina-o como seu negócio principal.

Prospecção com DataStack

Encontre novos endereços de e-mail comerciais e pessoais e importe-os direto para suas listas. As importações são descontadas do seu plano; as contagens são gratuitas.

  • GET /datastack/credits — quantos endereços seu plano ainda permite importar neste mês.
  • GET /datastack/count — quantos endereços existem para country, niche (categorias de negócio), keyword e role (pessoais). Gratuito.
  • POST /datastack/import — importa endereços business e/ou personal para list_uid (tarefa em segundo plano). Os novos endereços são verificados antes que qualquer campanha envie para eles.
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"list_uid":"cr5899rtqe668","business":2000,"country":"Greece","niche":"dentist, hotel"}' \
  https://mailflow.top/api/index.php/datastack/import

{"status":"success","data":{"job_id":513,"job_status":"queued","check":"/ai/jobs/513","list_uid":"cr5899rtqe668"}}

Tickets de suporte

  • GET|POST /support-tickets — seus tickets; abra um com subject, message, category e priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — leia a conversa, responda, feche.

Permissões das chaves de API

Uma chave pode ser limitada a determinados endpoints. Em Conta → Chaves de API, edite a chave, ative as permissões e marque o que ela pode usar. Os endpoints desta página aparecem com o prefixo MailFlow.

Erros e limites

  • 400 — X-Api-Key ausente ou inválido, ou a chave não tem permissão para este endpoint
  • 402 — créditos do DataStack insuficientes neste mês
  • 403 — o recurso não está incluído no seu plano, ou um limite do plano foi atingido
  • 404 — a lista, campanha ou outro item não existe na sua conta
  • 409 — o item não está no estado adequado (por exemplo, só rascunhos podem ser aprovados)
  • 422 — parâmetros ausentes/inválidos
  • 429 — limite de créditos de IA ou cota mensal de IA atingido; renova na sua próxima data de cobrança

Picos de requisições são limitados por chave — implemente backoff exponencial ao receber 429. Dúvidas? Fale conosco ou abra um ticket de suporte.