Documentação API

IAGENTEmail API

Gerencie contatos, grupos e listas de email marketing via REST API. Autenticação por API Key e respostas em JSON.

Autenticação

Todas as requisições devem incluir o header IAGENTE-KEY com a chave de API fornecida no painel do IAGENTEmail.

Base URL

https://api.iagentemail.com/v1/

Header de Autenticação

IAGENTE-KEY: SUA_API_KEY_AQUI

Formato das Requisicoes

Todas as requisições devem ser enviadas via POST com os parâmetros no corpo da requisição em formato application/x-www-form-urlencoded ou application/json. Todas as respostas sao retornadas em JSON.

Contatos

POST /contact/create Criar contato

Cria um novo contato na base de emails.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
email string Sim Email do contato
nome string Nao Nome do contato
grupo_id int Nao ID do grupo para vincular o contato

Exemplos

curl -X POST "https://api.iagentemail.com/v1/contact/create" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@empresa.com",
    "nome": "Joao Silva",
    "grupo_id": 42
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/contact/create');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => 'joao@empresa.com',
    'nome' => 'Joao Silva',
    'grupo_id' => 42
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Contato criado com sucesso",
  "data": {
    "id": 10001,
    "email": "joao@empresa.com",
    "nome": "Joao Silva",
    "grupo_id": 42,
    "created_at": "2026-03-26 10:00:00"
  }
}
Resposta de Erro
{
  "status": "error",
  "message": "Email ja cadastrado na base"
}
POST /contact/list Listar contatos

Retorna todos os contatos da conta, independente de grupo.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
pagina int Nao Numero da pagina (default: 1)
limite int Nao Registros por pagina (default: 50, max: 200)
status string Nao Filtrar por status: ativo, inativo, bounce, cancelado
busca string Nao Buscar por nome ou email

Exemplos

curl -X POST "https://api.iagentemail.com/v1/contact/list" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "pagina": 1,
    "limite": 100,
    "status": "ativo"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/contact/list');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'pagina' => 1,
    'limite' => 100,
    'status' => 'ativo'
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "data": {
    "contatos": [
      {
        "id": 10001,
        "email": "joao@empresa.com",
        "nome": "Joao Silva",
        "status": "ativo",
        "grupos": [42],
        "created_at": "2026-03-26 10:00:00"
      },
      {
        "id": 10002,
        "email": "maria@empresa.com",
        "nome": "Maria Santos",
        "status": "ativo",
        "grupos": [42, 43],
        "created_at": "2026-03-25 14:30:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 5,
      "total_registros": 487,
      "limite": 100
    }
  }
}
POST /contact/edit Editar contato

Atualiza os dados de um contato existente.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
id int Sim ID do contato
email string Nao Novo email
nome string Nao Novo nome
status string Nao Novo status: ativo, inativo

Exemplos

curl -X POST "https://api.iagentemail.com/v1/contact/edit" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10001,
    "nome": "Joao Carlos Silva",
    "email": "joaocarlos@empresa.com"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/contact/edit');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'id' => 10001,
    'nome' => 'Joao Carlos Silva',
    'email' => 'joaocarlos@empresa.com'
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Contato atualizado com sucesso",
  "data": {
    "id": 10001,
    "email": "joaocarlos@empresa.com",
    "nome": "Joao Carlos Silva",
    "status": "ativo",
    "updated_at": "2026-03-26 11:00:00"
  }
}
Resposta de Erro
{
  "status": "error",
  "message": "Contato nao encontrado"
}
POST /contact/remove Remover contato

Remove permanentemente um contato da base.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
id int Sim ID do contato

Exemplos

curl -X POST "https://api.iagentemail.com/v1/contact/remove" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10001
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/contact/remove');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'id' => 10001
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Contato removido com sucesso"
}
Resposta de Erro
{
  "status": "error",
  "message": "Contato nao encontrado"
}
POST /contact/mass/add Adição em massa

Adiciona múltiplos contatos de uma vez. Ideal para importacao de listas.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
contatos array Sim Lista de contatos com email e nome
grupo_id int Nao ID do grupo para vincular todos os contatos
atualizar_existentes boolean Nao Se true, atualiza contatos ja existentes (default: false)

Exemplos

curl -X POST "https://api.iagentemail.com/v1/contact/mass/add" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "grupo_id": 42,
    "atualizar_existentes": true,
    "contatos": [
      {
        "email": "joao@empresa.com",
        "nome": "Joao Silva"
      },
      {
        "email": "maria@empresa.com",
        "nome": "Maria Santos"
      },
      {
        "email": "pedro@empresa.com",
        "nome": "Pedro Oliveira"
      },
      {
        "email": "ana@empresa.com",
        "nome": "Ana Costa"
      },
      {
        "email": "carlos@empresa.com",
        "nome": "Carlos Ferreira"
      }
    ]
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/contact/mass/add');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'grupo_id' => 42,
    'atualizar_existentes' => true,
    'contatos' => [
        ['email' => 'joao@empresa.com', 'nome' => 'Joao Silva'],
        ['email' => 'maria@empresa.com', 'nome' => 'Maria Santos'],
        ['email' => 'pedro@empresa.com', 'nome' => 'Pedro Oliveira'],
        ['email' => 'ana@empresa.com', 'nome' => 'Ana Costa'],
        ['email' => 'carlos@empresa.com', 'nome' => 'Carlos Ferreira']
    ]
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Importacao concluida",
  "data": {
    "total_enviados": 5,
    "criados": 3,
    "atualizados": 2,
    "erros": 0,
    "detalhes_erros": []
  }
}
Resposta com Erros Parciais
{
  "status": "success",
  "message": "Importacao concluida com erros",
  "data": {
    "total_enviados": 5,
    "criados": 3,
    "atualizados": 1,
    "erros": 1,
    "detalhes_erros": [
      {
        "email": "email-invalido",
        "erro": "Formato de email invalido"
      }
    ]
  }
}

Grupos

POST /group/create Criar grupo

Cria um novo grupo (lista) de contatos.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
nome string Sim Nome do grupo
descrição string Nao Descrição do grupo

Exemplos

curl -X POST "https://api.iagentemail.com/v1/group/create" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Newsletter Mensal",
    "descrição": "Assinantes da newsletter mensal"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/group/create');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'nome' => 'Newsletter Mensal',
    'descrição' => 'Assinantes da newsletter mensal'
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Grupo criado com sucesso",
  "data": {
    "id": 43,
    "nome": "Newsletter Mensal",
    "descrição": "Assinantes da newsletter mensal",
    "total_contatos": 0,
    "created_at": "2026-03-26 10:05:00"
  }
}
POST /group/list Listar grupos

Retorna todos os grupos da conta.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
pagina int Nao Numero da pagina (default: 1)
limite int Nao Registros por pagina (default: 50)

Exemplos

curl -X POST "https://api.iagentemail.com/v1/group/list" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "pagina": 1,
    "limite": 50
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/group/list');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'pagina' => 1,
    'limite' => 50
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "data": {
    "grupos": [
      {
        "id": 42,
        "nome": "Clientes Ativos",
        "descrição": "Lista de clientes com contrato ativo",
        "total_contatos": 150,
        "created_at": "2026-01-15 08:00:00"
      },
      {
        "id": 43,
        "nome": "Newsletter Mensal",
        "descrição": "Assinantes da newsletter mensal",
        "total_contatos": 0,
        "created_at": "2026-03-26 10:05:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 1,
      "total_registros": 2,
      "limite": 50
    }
  }
}
POST /group/edit Editar grupo

Atualiza os dados de um grupo existente.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
id int Sim ID do grupo
nome string Nao Novo nome do grupo
descrição string Nao Nova descrição

Exemplos

curl -X POST "https://api.iagentemail.com/v1/group/edit" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 42,
    "nome": "Clientes Premium",
    "descrição": "Lista de clientes com plano premium"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/group/edit');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'id' => 42,
    'nome' => 'Clientes Premium',
    'descrição' => 'Lista de clientes com plano premium'
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Grupo atualizado com sucesso",
  "data": {
    "id": 42,
    "nome": "Clientes Premium",
    "descrição": "Lista de clientes com plano premium",
    "total_contatos": 150,
    "updated_at": "2026-03-26 11:10:00"
  }
}
POST /group/remove Remover grupo

Remove um grupo. Os contatos vinculados nao sao excluidos da base, apenas desvinculados do grupo.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
id int Sim ID do grupo

Exemplos

curl -X POST "https://api.iagentemail.com/v1/group/remove" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 43
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/group/remove');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'id' => 43
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Grupo removido com sucesso"
}
Resposta de Erro
{
  "status": "error",
  "message": "Grupo nao encontrado"
}
POST /group/contact/list Contatos do grupo

Retorna a lista de contatos vinculados a um grupo especifico.

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
grupo_id int Sim ID do grupo
pagina int Nao Numero da pagina (default: 1)
limite int Nao Registros por pagina (default: 50, max: 200)

Exemplos

curl -X POST "https://api.iagentemail.com/v1/group/contact/list" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "grupo_id": 42,
    "pagina": 1,
    "limite": 50
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/group/contact/list');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'grupo_id' => 42,
    'pagina' => 1,
    'limite' => 50
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "data": {
    "contatos": [
      {
        "id": 10001,
        "email": "joao@empresa.com",
        "nome": "Joao Silva",
        "status": "ativo",
        "created_at": "2026-03-26 10:00:00"
      },
      {
        "id": 10002,
        "email": "maria@empresa.com",
        "nome": "Maria Santos",
        "status": "ativo",
        "created_at": "2026-03-25 14:30:00"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 3,
      "total_registros": 150,
      "limite": 50
    }
  }
}
POST /group/contact/remove Remover contato do grupo

Remove um contato de um grupo especifico (sem excluir o contato da base).

Parâmetros (Body JSON)

Parâmetro Tipo Obrigatório Descrição
contato_id int Sim ID do contato
grupo_id int Sim ID do grupo

Exemplos

curl -X POST "https://api.iagentemail.com/v1/group/contact/remove" \
  -H "IAGENTE-KEY: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "contato_id": 10001,
    "grupo_id": 42
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.iagentemail.com/v1/group/contact/remove');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'IAGENTE-KEY: SUA_API_KEY_AQUI',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'contato_id' => 10001,
    'grupo_id' => 42
]));

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

$data = json_decode($response, true);
print_r($data);
?>
Resposta de Sucesso
{
  "status": "success",
  "message": "Contato removido do grupo com sucesso"
}
Resposta de Erro
{
  "status": "error",
  "message": "Contato nao pertence ao grupo informado"
}

Codigos de Status HTTP

Codigo Descrição
200 Requisicao bem-sucedida
400 Requisicao inválida (parâmetros faltando)
401 Chave API inválida ou ausente
404 Recurso nao encontrado
422 Dados invalidos (validacao falhou)
429 Rate limit excedido
500 Erro interno do servidor

Precisa de ajuda? Entre em contato com nosso suporte tecnico pelo WhatsApp ou acesse a Central de Ajuda.