Ajuda

Você pode integrar o seu site para salvar os contatos dentro da sua conta da MailerWeb sem a necessidade de importar arquivos volumosos para dentro do nosso sistema. Nos passos abaixo você verá como criar um contato dentro e fazer uso do nosso sistema de validação de contatos.

Para se integrar à API é necessário que você esteja autenticado e para isso é importante que você tenha acesso ao artigo "Como se integrar a API da MailerWeb?"

Passo 1 - Criando uma Lista Estática

Para criar contatos na nossa base de dados, primeiro temos de interagir com a API de Listas Estáticas, onde iremos criar a lista estática onde obrigatoriamente devemos associar os contatos. Contatos sem uma Lista Estática associada não pode ser criado no sistema.

Para interagir com a Lista Estática, vamos criar a lista estática com o seguinte endpoint e parâmetros:

POST: /api/v1/contacts/static_list/

data = {
   'name': 'Nome da Lista'
}

curl --dump-header - -H "Content-Type: application/json" \
 -H "Authorization: ApiKey username:API_KEY"\
 -X POST --data data https://painel.mailerweb.com.br/api/v1/contacts/static_list/

O resultado esperado será semelhante ao JSON abaixo:

{
    "contacts_hard_bounce": 0,
    "contacts_soft_bounce": 0,
    "contacts_valids": 0,
    "date_created": "2020-01-10",
    "id": XXX_ID_LISTA,
    "last_updated": "2020-01-10",
    "name": "Nome da Lista",
    "resource_uri": "/api/v1/contacts/static_list/XXX_ID_LISTA/",
    "total_contacts": 0
}

Repare que o ID da Lista estática está no atributo ID e no atributo resource_url, onde você poderá acessar os detalhes da lista a partir do endpoint entregue por esse parâmentro. A partir de agora, grave esse ID, ele será utilizado para você criar os contatos dentro da sua base na MailerWeb.

Agora que você está de posse do ID da Lista, vamos ao Passo 2

Passo 2 - Criando os contatos

POST: /api/v1/contacts/contact/

data = {
   'name': 'Fulano de Tal e Qual',
   'email': 'fulano@domain.com',
   'phone': '+55219888888888'
   'tag_list':['XXX_ID_LISTA'],
}

curl --dump-header - -H "Content-Type: application/json" \
 -H "Authorization: ApiKey username:API_KEY"\
 -X POST --data data https://painel.mailerweb.com.br/api/v1/contacts/contact/

Algumas observações importantes:

• O atributo tag_list, necessariamente tem que receber o valor dentro dos colchetes, pois tag_list é uma lista, logo um contato pode estar associado a um ou mais Listas Estáticas
• O campo e-mail deve conter um e-mail válido.

A resposta esperada do servidor em caso de criação de contato com sucesso será a seguir:

{
    "campaigns": [],
    "clicked": false,
    "date_created": "2020-01-10T16:34:41.561242",
    "email": "fulano@domain.com",
    "email_format": "html",
    "id": "5e18c3c1ffdb0f1b42fa9XXX",
    "ip_address_confirmation": null,
    "ip_address_inclusion": "X.X.X.X",
    "is_confirmed": false,
    "last_updated": "2020-01-10T16:34:41.660670",
    "lead_score": "3",
    "name": "Fulano de Tal e Qual",
    "opt_out": false,
    "opt_out_reason": null,
    "resource_uri": "/api/v1/contacts/contact/5e18c3c1ffdb0f1b42fa9XXX/",
    "status": "ok",
    "tag_list": ["22"],
    "was_checked": false
}

Algumas observações:

• O campo status retorna a situação do contato ao ser inserido - se passou em todas as validações será dado como OK;
• Se o contato já tiver sido incluído e tido como Opt-Out, ele retornará como Opt-Out: True;
• O campo ip_address_inclusion irá registrar de qual máquina ele foi registrado.

Se houver um problema no campo e-mail por exemplo, e você tentar cadastrar como por exemplo, "fulano@hotamil.com" que na verdade é "fulano@hotmail.com", a API irá devolver o seguinte erro:

{"error": "E-mail incorreto, não seria fulano@hotmail.com ?"}

Abaixo segue as variações de erros que podem acontecer ao tentar incluir um contato:

• O valor para a lista XX está incorreto, verifique novamente o valor no campo tag_list ou crie uma lista com esse valor: É provável que você esteja tentando associar um contato a uma lista inexistente ou com ID incorreto;
• Você deve informar em quais Listas Estáticas para esse contato deve ser incluído no campo tag_list: É provável que você esteja tentando inserir um contato sem uma Lista Estática atribuída.
• E-mail existente na base de dados! Para atualizar os dados informe o parâmetro update: É provável que você esteja tentando criar um contato que já existe, para informações sobre como obter dados de um contato veja a seção "Como resgatar e editar dados de um contato via API?"
• O e-mail que você está tentando inserir é um e-mail inválido e não pode receber mensagens!: É provável que você esteja tentando criar um contato com um e-mail sabidamente inválido, essa operação não será permitido. Se ainda assim você acha que o e-mail pode ser criado tente remover da lista de supressão, através do menu Contatos > Remover da Lista de Supressão no painel de controle;
• O telefone está em um formato inválido, verifique se está inserido no formato correto!: Verifique se o telefone que você está tentando inserir está correto;

IMPORTANTE: Para adicionar um contato com um campos customizado você precisa adicionar o dicionário data, conforme o exemplo abaixo:

data = { 'name': 'Fulano de Tal e Qual',
   'email': 'fulano@domain.com',
   'phone': '+55219888888888'
   'tag_list':['XXX_ID_LISTA'],
   'gender': 'M'
} 

curl --dump-header - -H "Content-Type: application/json" 
\ -H "Authorization: ApiKey username:API_KEY"
\ -X POST --data data https://painel.mailerweb.com.br/api/v1/contacts/contact/

Nesse caso adicionamos o campo "Sexo" (gender), como um campo customizado, e depois faremos a inclusão do contato. Se o campo customizado não existir o dados será ignorado.