Configurações

API

Como importar uma base de contatos, criar uma segmentação e fazer um envio através da API


Como importar uma base de contatos, criar uma segmentação e fazer um envio por API.



Através de requisições via API você poderá realizar diversas ações como uma importação de contatos, filtrar uma base de contatos específica de acordo com comportamento ou dados de seu cadastro e ainda, realizar um envio de email.



Documentação de API


A documentação oficial da API está disponível no endereço: https://mail2easypro.com/apidoc/ 



Gerando um token de autenticação


Inicialmente, você deverá gerar um token de aplicação para autenticar-se no sistema.

Para concluir essa etapa, pode seguir esse guia: https://help.dinamize.com/article/4000128088-como-gerar-token-de-autenticacao-com-o-postman


Conforme descrito na documentação, é importante salientar que o token de acesso expira em 1 hora de inatividade e pode permanecer ativo por no máximo 24 horas. 



Adicionando Contatos 


Para realizar a inserção de contatos dentro do sistema é necessário possuir uma lista. 

O código da lista será utilizado para executar as requisições.


As listas são como subcontas em nossa plataforma, para quem gerencia diferentes clientes. Por padrão, caso você tenha um único cliente, o recomendado é trabalhar com uma única lista e realizar segmentações dentro dela a partir dos filtros, para envios para um público especifico.



É possível identificar esse código acessando a sua base e clicando no botão visualizar, conforme as figuras abaixo:





Verifique o código que aparece na URL. Ele representará o seu “contact-list_code”





Através de uma chamada via API também é possível consultar esse código:


https://mail2easypro.com/apidoc/#api-4ContactListGroup-ContactListSearch


Segue um exemplo desta ação via Postman:



E da resposta:







Importação de contatos



Seguindo a documentação, a opção CONTATOS - IMPORTAÇÃO - ADICIONAR nos permite criar uma requisição de importação de contatos.


Observe:


Para importar o código de comando do cURL no Postman:

 

  - Clique em "Import" 

 

 

 

  - Selecione a opção "Paste Raw Text", cole o comando cURL abaixo inserindo o seu token e clique em "import". 

 

 

curl --header 'auth-token: substituir token' -F 'file=@/arquivo.csv' -F 'command=import' -F 'parameters={"contact-list_code": "7", "separator": ";", "header": true, "file_columns": [{"Position":"0", "Field":"2", "Rule":"3"}, {"Position":"1", "Field":"1", "Rule":"3"}, {"Position":"2", "Field":"5", "Rule":"3", "Extras": {"separator":",", "action":"increment", "include_new_values":true} } ] }' http://api.dinamize.com/emkt/contact

 


É importante que você informe o código da lista que você está trabalhando.


A posição do campo da sua planilha deve ser definida através da variável “position”. 

Já a variável “field” deverá ser relacionada com o dado que você tem criado na sua base de dados da lista.



Na planilha:




No sistema:

 


Como a requisição deverá ser incluída:



Clique no botão import e procure pelo arquivo que será importado, selecionando a opção “file”.





Clique no botão send e verifique a importação através do menu Contatos >> Listas >> Visualizar:




Outras opções de cadastro de contatos


Adicionando contatos de forma unitária


Assim como operações em massa, também é possível adicionar contatos de forma única.

Essa requisição deverá ser utilizada quando você tiver interesse em cadastrar apenas um contato por vez. 


Lembrando que, por padrão, a API possui um limite de 60 requisições por minuto. Para obter o status do limite, consulte o parâmetro "retry-after" no retorno da chamada.


IMPORTANTE: Se a intenção for cadastrar contatos em lote, você deverá usar sempre a importação (mencionada no artigo acima).


Abaixo vamos exemplificar uma situação de cadastro manual:


Inicialmente você deverá utilizar a requisição da API disponível no link:

https://mail2easypro.com/apidoc/#api-5ContactGroup-ContactAdd





Você deverá inserir o email a ser cadastrado, o nome do contato e os campos personalizados que tem cadastrado em sua lista.


Em nosso exemplo, o campo “cmp4” corresponde a qual o código do marcador que desejamos atribuir esse contato.


O campo "cmp5" corresponde ao código da lista de valores únicos que temos no campo cidade.


E por fim, o parâmetro contact-list_code corresponde ao código da lista que estamos trabalhando.



Na figura abaixo visualizamos os campos de nossa lista e os códigos:



A mesma consulta pelos campos pode ser realizada através da requisição disponível no link abaixo:


https://mail2easypro.com/apidoc/#api-8FieldGroup-FieldSearch


Após clicar no botão send e verificar o retorno de sucesso, você poderá acessar a interface gráfica e observar que nosso contato foi adicionado na plataforma:






Adicionando contatos através de um formulário de integração


Se você deseja realizar a integração de um formulário no seu site com nosso sistema, você não precisará , necessariamente, fazer uso direto da API.


Esse vínculo pode ser criado a partir da geração de um código de formulário e posteriormente adicionado na sua página, possibilitando o envio de dados cadastrados automaticamente para a plataforma.

Para saber mais sobre esse processo, você pode verificar neste link.


Caso você tenha contratado o MKT2Easy é possível gerar um código dentro da plataforma, que após inserido nas páginas desejadas, possibilitará capturar os dados de formulários já existentes no seu site.

Para entender melhor sobre esse processo, acesse esse link.


Como fazer uma segmentação:


Através de requisições também é possível realizar filtragens e segmentar os contatos da sua base, podendo inclusive utilizar disparos especificamente para esse público.


No exemplo abaixo vamos criar um filtro que contenha apenas os contatos que são da cidade de Porto Alegre que cadastramos na planilha.



Acessando novamente o Postman você deverá importar o código abaixo:


curl --header 'Content-Type: application/json; charset=utf-8' --header 'auth-token: substituir token' --data '{  "contact-list_code":"7",  "title":"Filtro API",  "type":"AND",  "rule_list": [             {"type": "C", "reverse":false, "rule": {"field":"1", "operator":"EQUAL", "value":"1"}}   ]}' https://api.dinamize.com/emkt/filter/add





Vamos entender o que os parâmetros representam:


Title: Será o nome do filtro que estamos criando.

Type:Representa o tipo de filtro, que em nosso exemplo é referente a busca de uma campo da lista, a cidade.

Operator: Representa qual operador lógico estará sendo usado na consulta.

Value: Representa o valor do campo previamente cadastrado que estamos consultando.


Na lista abaixo é possível analisar os operadores que podem ser utilizados nessa filtragem:



Operator

String

Operador do campo

Texto simples (EQUAL, !EQUAL, LIKE, !LIKE, STARTS_WITH, !STARTS_WITH, ENDS_WITH, !ENDS_WITH, VC_EMPTY, !VC_EMPTY)
Numérico (EQUAL, !EQUAL, GREATER_THAN, LESS_THAN)
Decimal (EQUAL, !EQUAL, GREATER_THAN, LESS_THAN)
Data (EQUAL, !EQUAL, GREATER_THAN, LESS_THAN, D_EMPTY, !D_EMPTY)
Data hora (EQUAL, !EQUAL, GREATER_THAN, LESS_THAN, D_EMPTY, !D_EMPTY)
Lista de valores únicos (EQUAL, !EQUAL, LV_EMPTY, !LV_EMPTY)
Lista de valores múltiplos (HAS, !HAS, IN, !IN, LV_EMPTY, !LV_EMPTY, LV_EXACTLY)




Após o retorno de sucesso, você poderá visualizar na interface gráfica, o filtro criado. Acessando o menu Contatos >> Segmentações:









Como realizar um envio por API.


Depois de incluir contatos na sua lista e realizar filtragens, você poderá realizar envios a partir de requisições usando a API do sistema.


Primeiramente devemos criar uma chamada para adicionar o envio no sistema e atribuir o HTML que será disparado, seja via url ou por conteúdo.


Abaixo temos um exemplo de como criar uma nova mensagem:


curl --header 'Content-Type: application/json; charset=utf-8' --header 'auth-token: substituir token' --data '{  "title":"Mensagem de teste",  "html":"Olá mundo! Este é um envio pela API"}' https://api.dinamize.com/emkt/message/add




Você deve definir o título e o HTML que será adicionado na mensagem:







Ao enviar a requisição será disponibilizado o código da mensagem criada:




Importante: Para criar mensagem através de nosso editor deve-se utilizar a URL: https://mail2easypro.com/#!/mkt/send/messages, após criada a mensagem será disponibilizado o ID desta mensagem e poderá utilizá-la.



Após essa etapa, devemos configurar o envio adicionando as informações pertinentes ao disparo como o assunto, remetente, etc.


Para configurar um novo envio você deverá utilizar a chamada abaixo:


curl --header 'Content-Type: application/json; charset=utf-8' --header 'auth-token: substituir token' --data '{  "title":"Test action",  "contact-list_code":"7",  "subject":"Test subject",  "sender_name":"Test sender name",  "sender_email":"nicolas@dinamizeweb.com.br",  "reply_to":"nicolas@dinamizeweb.com.br",  "campaign_code":"1",  "filter_code":"2",  "message_code":"9",  "message_type":"CAD",  "send_speed":"2",  "send_now":true,  "optout_progressMode":"DI"}' https://api.dinamize.com/emkt/action/add




Vamos analisar as informações de alguns parâmetros do envio que deverão ser substituídos:





subject: Assunto da mensagem

sender_name: Corresponde ao nome do remetente

sender_email: O email que está realizando o envio com o domínio cadastrado

filter_codeCódigo do filtro que criamos com o público que receberá o disparo.

message_code: Representa o código da mensagem que geramos na requisição anterior.




Após realizar o envio, podemos verificar o relatório da mensagem com as informações que preenchemos anteriormente:






Ainda no relatório, é possível analisar qual o contato que participou do envio:





Pronto, realizamos o processo completo de importação, segmentação e envio pela API.


Acompanhe os principais tutoriais sobre nossa integração API