Construa suas próprias integrações com o Mailzen.

Uma API REST para toda a plataforma

A API do Mailzen é REST, retorna respostas em JSON e dá acesso programático aos principais recursos da plataforma. Com ela, você pode automatizar tarefas, sincronizar dados com outros sistemas e construir integrações personalizadas.

Recursos disponíveis atualmente:

• Contacts
• Lists
• Tags
• Segments
• Campaigns
• Templates
• Automations
• Forms
• Domains

Autenticação por API Key

Todas as requisições à API precisam ser autenticadas com uma API Key, gerada dentro do próprio app do Mailzen. A chave deve ser enviada no cabeçalho Authorization de cada requisição, como Bearer token:

Authorization: Bearer {sua-api-key}

Guarde sua API Key com segurança — ela concede acesso à sua conta pela API. Nunca exponha a chave em código que roda no navegador ou em repositórios públicos.

Exemplos de requisição

Criar um contato

POST /api/v1/contacts

const response = await fetch("https://api.mailzen.com.br/api/v1/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {sua-api-key}",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "ana.silva@example.com",
    name: "Ana Silva",
    list_id: "list_8f21a",
    tags: ["lead", "webinar-2026"]
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.mailzen.com.br/api/v1/contacts",
    headers={
        "Authorization": "Bearer {sua-api-key}",
        "Content-Type": "application/json"
    },
    json={
        "email": "ana.silva@example.com",
        "name": "Ana Silva",
        "list_id": "list_8f21a",
        "tags": ["lead", "webinar-2026"]
    }
)

print(response.json())

<?php

$ch = curl_init("https://api.mailzen.com.br/api/v1/contacts");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {sua-api-key}",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "email" => "ana.silva@example.com",
    "name" => "Ana Silva",
    "list_id" => "list_8f21a",
    "tags" => ["lead", "webinar-2026"]
]));

$response = curl_exec($ch);
curl_close($ch);

echo $response;

curl -X POST https://api.mailzen.com.br/api/v1/contacts \
  -H "Authorization: Bearer {sua-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana.silva@example.com",
    "name": "Ana Silva",
    "list_id": "list_8f21a",
    "tags": ["lead", "webinar-2026"]
  }'

Exemplo de resposta:

{
  "id": "contact_3f9a1c",
  "email": "ana.silva@example.com",
  "name": "Ana Silva",
  "list_id": "list_8f21a",
  "tags": ["lead", "webinar-2026"],
  "status": "subscribed",
  "created_at": "2026-08-19T14:32:00Z"
}

Listar contatos

GET /api/v1/contacts

curl https://api.mailzen.com.br/api/v1/contacts \
  -H "Authorization: Bearer {sua-api-key}"

Exemplo de resposta:

{
  "data": [
    {
      "id": "contact_3f9a1c",
      "email": "ana.silva@example.com",
      "name": "Ana Silva",
      "status": "subscribed"
    },
    {
      "id": "contact_7b02de",
      "email": "carlos.souza@example.com",
      "name": "Carlos Souza",
      "status": "subscribed"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 132
}

Criar uma campanha

POST /api/v1/campaigns

curl -X POST https://api.mailzen.com.br/api/v1/campaigns \
  -H "Authorization: Bearer {sua-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter de agosto",
    "subject": "As novidades do mês para você",
    "template_id": "tpl_newsletter_01",
    "list_id": "list_8f21a",
    "scheduled_at": "2026-08-25T09:00:00Z"
  }'

Exemplo de resposta:

{
  "id": "campaign_a19cf3",
  "name": "Newsletter de agosto",
  "subject": "As novidades do mês para você",
  "status": "scheduled",
  "scheduled_at": "2026-08-25T09:00:00Z"
}

Webhooks

Webhooks permitem que o Mailzen notifique o seu sistema em tempo real quando determinados eventos acontecem, enviando uma requisição HTTP POST para uma URL configurada por você — sem que seja preciso ficar consultando a API repetidamente.

Eventos que podem disparar um webhook:

• Contato criado
• Contato atualizado
• E-mail entregue
• E-mail aberto
• Link clicado
• Descadastro (unsubscribe)
• Bounce

Rate limits

Para manter a estabilidade da plataforma, a API aplica limites de número de requisições por minuto, que variam conforme o plano contratado. Ao atingir o limite, a API retorna o código de erro 429.

Limites exatos: consulte a documentação de desenvolvedores

Códigos de erro

A API utiliza códigos de status HTTP convencionais para indicar o resultado de cada requisição.

Paginação

Endpoints que retornam listas, como GET /api/v1/contacts, seguem uma convenção de paginação para não devolver todos os registros de uma vez — normalmente por parâmetros como page/per_page ou limit/cursor, dependendo do recurso.

Detalhes exatos na documentação de desenvolvedores

Versionamento

A API é versionada por meio de um prefixo na própria URL, como em /api/v1/. Isso permite que novas versões sejam lançadas no futuro sem quebrar integrações que já estão em produção usando uma versão anterior.