Nessa sessão demonstraremos como é possível criar automatização de envio através da Régua de Campanha, por meio da API da MailerWeb.

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?". Para essa sessão se faz necessário conhecimentos sobre "Como criar um Modelo de Envio de E-mail Marketing utilizando a API", "Como criar um Modelo de Envio de SMS Marketing utilizando a API", "Como criar um Modelo de Envio de WhatsApp Marketing utilizando a API" e para o caso específico de E-mail Marketing, "Como criar um Remetente de Envio de E-mail Marketing utilizando a API".

Passo 1 - Criando uma Régua de Campanha

Com esse método você poderá criar automatizações de envio de mensagens, através da criação campanhas automáticas, que serão criadas a partir de definições de que você irá configurar no sistema. Para saber mais sobre o funcionamento das Réguas de Campanha, clique aqui. Abaixo listamos os atributos que deverão ser utilizados para se criar uma régua de campanha:

• Campo "name", utilizado para identificar a Régua de Campanha, um nome para se lembrar sobre o que versa essa régua;
• Campo "pause_on_error", tipo Booleano, valor padrão False, se refere se a régua de campanha deve parar a sua execução (ela é colocada em modo "Edição") se acontecer algum erro durante a execução, como por exemplo, ausência de contatos para executar a régua;
• Campo "send_remaining", tipo Booleano, valor padrão False, se refere se em caso de término de quota de envio, a campanha deverá ser executada até o término da quota, ou campanha vinculada deverá ser cancelada e não executada;
• Campo "start_date", tipo Date, deverá ser no formato "YYYY-MM-DD", informa para quando a régua deve criar a 1a campanha;
• Campo "end_date", tipo Date, deverá ser no formato "YYYY-MM-DD", informa a data limite para criação de campanhas por aquela régua;
• Campo "status', tipo Caracter, com as seguintes opções válidas:
  • draft - Em edição, a régua não irá enviar campanhas enquanto estiver nesse status;
  • enabled - Ativada, se a régua for colocada nesse modo, ela programará a campanha;
  • finished -  Finalizada, a régua já cumpriu todos os passos e foi encerrada;
  • canceled - A régua foi cancelada devido alguma intercorrência do usuário, como por exemplo, falta de pagamento;

A chamada para a criação de uma régua de campanha seguirá  o exemplo abaixo:

POST: /api/v1/campaigns/rule/

data = {
    "name": "Teste",
    "start_date": "2020-11-15"
}

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/campaigns/rule/

O resultado esperado é o retorno 201 do servidor, com os dados do objeto postado.

{
    "meta": {
        "limit": 50,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "end_date": "2018-04-30T00:00:00",
            "id": id-da-regua,
            "name": "Teste",
            "pause_on_error": false,
            "resource_uri": "/api/v1/campaigns/rule/id-da-regua/",
            "send_remaining": false,
            "start_date": "2018-04-09T00:00:00",
            "status": "draft"
        }
    ]
}

Repare que o ID da Régua de Campanha está no atributo ID e no atributo resource_url, onde você poderá acessar os detalhes dessa campanha a partir do endpoint entregue por esse parâmetro. A partir de agora, grave esse ID, todos os detalhes de relatório e filtro de contatos você poderá fazer a partir desse ID.

Passo 2 - Listando suas Réguas de Campanha

Para visualizar todas as réguas de campanha, criadas na usa conta, utilize o método abaixo:

GET: /api/v1/campaigns/rule

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/campaigns/rule/ 

O resultado será semelhante a esse:

{
    "meta": {
        "limit": 50,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "end_date": "2018-04-30T00:00:00",
            "id": id-da-regua-de-campanha,
            "name": "Teste",
            "pause_on_error": false,
            "resource_uri": "/api/v1/campaigns/rule/id-da-regua-de-campanha/",
            "send_remaining": false,
            "start_date": "2018-04-09T00:00:00",
            "status": "draft"
        }
    ]
}

Importante notar que será exibido um objeto no formato JSON, onde virão 2 dicionários: meta e objects, a saber:

• Em "meta" você terá uma visão geral de quantos objetos você possui e ainda o link da próxima página do objeto, isso estará no atributo "next" do dicionário;
• Em objects, você terá um detalhe completo do objeto carregado no campo resource_uri, terá o link para chamar para a atualização desse objeto.

Você também poderá consultar objetos de acordo com os atributos existentes nesse formulário, por exemplo:

Listando por ID da Regua de Campanha:

• GET: /api/v1/campaigns/rule/?id=xxx

Listando por Nome da Régua de Campanha

• GET: /api/v1/campaigns/rule/?name=xxx

Passo 3 - Criando um Item de uma Régua de Campanha

De posse do ID da Régua de Campanha, agora devemos prosseguir na criação dos Itens da Régua de Campanha, utilizaremos os campos abaixo para a criação de um Item de uma Régua de Campanha:

• Campo "rule", utilizado para vincular a uma Régua de Campanha, é do tipo caracter e deverá ser inserido no formato: "/api/v1/campaigns/rule/id-da-regua-de-campanha";
   
• Campo "name", do tipo caracter utilizado para identificar o nome do Item da Régua de Campanha;
   

Campo "parent", do tipo caracter, é utilizado para determinar um Item de Régua de Campanha, como subordinado a outro "Item de Régua de Campanha" da mesma "Regua de Campanha", deverá ser inserido no formato "/api/v1/campaigns/rule_item/id-do-item-da-regua-de-campanha-pai". ATENÇÃO: SOMENTE SERÁ ADMITIDO UM ITEM SEM O CAMPO PARENT POR RÉGUA. Caso você coloque mais de um item sem o campo parent na régua, ela perderá o ponto de partida e não será disparada;

• Campo "sending_type", do tipo caracter, porém somente admitidos os valores abaixo:
  • email: para executar campanhas de e-mail marketing;
  • sms: para executar campanhas de sms marketin;
  • whatsapp: para executar campanhas de WhatsApp marketing;
     
• Campo "email_sender", do tipo caracter, é obrigatório apenas quando definido que o "sending_type" é do tipo "email", ele vincula o objeto Remetente de Envio, deverá ser no formato "/api/v1/campaigns/sender/id-do-remetente";
   
• Campo "use_my_number", do tipo booleano, disponível apenas quando definido que o "sending_type" é do tipo "whatsapp", admite "true" ou "false";
   
• Campo "whatsapp_sender", do tipo caracter, é obrigatório apenas, quando "use_my_number" for definido como "true", você deverá possui um número WhatsApp autenticado no sistema, maiores informações veja em "Como autenticar o meu número de Envio de WhatsApp";
   

• Campo "reply_mobile_number", é utilizado para as campanhas que utilizam o número da MailerWeb, você poderá definir um telefone para receber as respostas da sua campanha. Ele será colocado na mensagem no formato de um link para abertura do aplicativo do WhatsApp. Caso tenha marcada o opção use_my_number como verdadeiro, esse campo "reply_mobile_number" será ignorado.

• Campo "reply_call_to_action", é utilizado para as campanhas que utilizam o número da MailerWeb, você poderá definir um texto que combinado com o valor do "reply_mobile_number" criará um link com texto na mensagem, chamando o contato para clicar no número do WhatsApp. Caso tenha marcada o opção use_my_number como verdadeiro, esse campo "reply_call_to_action" será ignorado.

• Campo "reply_contact_text", é utilizado para as campanhas que utilizam o número da MailerWeb, você poderá definir um texto que será exibido dentro do aplicativo do WhatsApp Web do contato, para que o contato receptor não precise digitar nenhuma mensagem para você, bastando apenas de ter de enviar a mensagem. Caso tenha marcada o opção use_my_number como verdadeiro, esse campo "reply_contact_text" será ignorado.

• Campo "reply_to" é utilizado para você designar um e-mail de resposta diferente do remetente, você pode enviar a partir do e-mail "no-reply@dominio.com.br" e quando o contato desejar responder sua mensagem, ele automaticamente pode redirecionado para o e-mail "contato@dominio.com.br".
   
• Campo "template" é utilizado para designar qual o modelo de mensagem você irá utilizar, deverá seguir o formato:
  • '/api/v1/campaigns/email_template/id-do-email-template' para modelos de mensagens para campanha de e-mail marketing;
  • '/api/v1/campaigns/sms_template/id-do-sms-template' para modelos de mensagens para campanha de SMS marketing;
  • '/api/v1/campaigns/whatsapp_template/id-do-whatsapp-template' para modelos de mensagens para campanha de WhatsApp marketing;
     
• Campo "lists" é utilizado para designar quais as listas que você utilizará para enviar as campanhas, será um campo do tipo lista, com vário itens, conforme formato abaixo:
  • /api/v1/contacts/static_list/id-da-lista-estatica/ se você desejar utilizar uma lista estática
  • /api/v1/contacts/dynamic_list/id-da-lista-dinamica/, se você desejar utilizar uma lista dinâmica. Campo "exclude_lists" é utilizado para designar quais listas cujo contatos também estejam no campo "lists", isso é feito para selecionar contatos que NAO devem receber a campanha, caso estejam designados no campos "lists";
     
• Campo "exclude_lists" é utilizado para designar que os contatos da campanha das listas selecionadas, estiverem na lista designada, não deverão receber a campanha, será um campo do tipo lista, com vário itens, conforme formato abaixo:
  • /api/v1/contacts/static_list/id-da-lista-estatica/ se você desejar utilizar uma lista estática
  • /api/v1/contacts/dynamic_list/id-da-lista-dinamica/, se você desejar utilizar uma lista dinâmica. Campo "exclude_lists" é utilizado para designar quais listas cujo contatos também estejam no campo "lists", isso é feito para selecionar contatos que NAO devem receber a campanha, caso estejam designados no campos "exclude_lists";
     
• Campo "open_lists", do tipo array, é utilizado para adicionar o contato a uma ou mais listas caso ele abra a campanha de e-mail marketing, deverá seguir o mesmo formato do campo "lists";
   
• Campo "click_lists", do tipo array, é utilizado para adicionar o contato a uma ou mais listas caslo ele clique na campanha de e-mail marketing.
• Campo "exclude_hard_bounced", do tipo booleano, é utilizado para excluir da seleção de contatos, aqueles que estejam classificados como Erros Permanentes, ou seja, contatos que são e-mail inexistentes, domínios que não existem mais. Esse campo por padrão é "true", se colocar como "false" existe o risco da sua campanha ser cancelada por excesso de erros.
   
• Campo "subject", do tipo caracter (linha simples) é utilizado para diferenciar o assunto daquele que foi definido por padrão na criação do Modelo de Envio de E-mail Marketing. Por padrão ele definido como "null", ele carrega a informação do objeto Modelo de Envio de E-Marketing, se colocado outro valor, o assunto da campanha passa a assumir este campo.
   
• Campo "create_dyn_list_from_not_in_rule", do tipo booleano, deverá ser marcado apenas para buscar contatos que ainda não participaram da régua de campanha;
   
• Campo "create_dyn_list_from_previous_campaigns", do tipo booleano, deverá ser marcado para utilizar os contatos que participaram da campanha anterior, realizada pela Régua de Campanha, podendo ter sido executado por este item ou por outro;
   
• Campo "create_dyn_list_from_not_previous_campaigns", do tipo booleano, deverá ser marcado para utilizar os contatos NÃO participaram da campanha anterior, realizada pela Régua de Campanha, podendo ter sido executado por este item ou por outro;
   
• Campo "create_dyn_list_from_opens",  do tipo booleano, deverá ser marcado para utilizar os contatos participaram da campanha anterior e fizeram abertura da mensagem, realizada pela Régua de Campanha, podendo ter sido executado por este item ou por outro;
   
• Campo "create_dyn_list_from_not_opens", do tipo booleano, deverá ser marcado para utilizar os contatos participaram da campanha anterior e NÃO fizeram abertura da mensagem, realizada pela Régua de Campanha, podendo ter sido executado por este item ou por outro;
   
• Campo "create_dyn_list_from_clicks",  do tipo booleano, deverá ser marcado para utilizar os contatos participaram da campanha anterior que fizeram abertura da mensagem e clicaram na mensagem, realizada pela Régua de Campanha, podendo ter sido executado por este item ou por outro;
   
• Campo "create_dyn_list_from_not_clicks", do tipo booleano, deverá ser marcado para utilizar os contatos participaram da campanha anterior que fizeram abertura da mensagem e NÃO clicaram na mensagem, realizada pela Régua de Campanha, podendo ter sido executado por este item ou por outro;
   
• Campo "interval_vaue", do tipo Inteiro Positivo, informa a quantidade de tempo que deverá ser criada uma campanha, após a campanha do item da régua anterior ter sido executado;
• Campo "interval_period", do tipo caracter, é unidade para definir a unidade tempo entre a execução de cada Item da Régua de Campanha, são admitidos os seguintes valores:
  • "day", para definir o intervalo em dias;
  • "month", para definir o intervalo em meses;
  • "year", para definir o intervao em anos;
     
• Campo "time" do tipo hora, é utilizado para definir o horário que o Item da Régua de Campanha deverá ser executado, as horas devem ser inserida no formato HH:MM, em formato 24 horas;
• Campo "run_on_days", do tipo array, opcional, somente é utilizado para designar em quais dias da semana, o Item da Régua de Campanha deverá ser executado, o valores admitidos estão abaixo descritos:
  • 0 - Segunda-feira
  • 1 - Terça-feira
  • 2 - Quarta-feira
  • 3 - Quinta-feira
  • 4 - Sexta-feira
  • 5 - Sábado
  • 7 - Domingo

O endpoint a seguir deverá ser utilizado para criar um Item de Régua de Campanha

POST: /api/v1/campaigns/rule_item/

data = {
    "rule": "/api/v1/campaigns/rule/id-regua-campanha/",
    "name": "Passo 1",
    "sending_type" : "email",
    "email_sender": "/api/v1/campaigns/sender/id-do-remetente/",
    "template": "/api/v1/campaigns/email_template/id-do-email-templte/",
    "subject": "teste",
    "time": "09:00",
    "interval_value": 0,
    "interval_period": "day",
    "lists": ["/api/v1/contacts/static_list/id-da-lista-estatica/"]
}

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/campaigns/rule_item/

O resultado esperado é o retorno 201 do servidor, com os dados do objeto postado.

{
    "click_lists": [],
    "create_dyn_list_from_clicks": false,
    "create_dyn_list_from_not_clicks": false,
    "create_dyn_list_from_not_in_rule": false,
    "create_dyn_list_from_not_opens": false,
    "create_dyn_list_from_not_previous_campaigns": false,
    "create_dyn_list_from_opens": false,
    "create_dyn_list_from_previous_campaigns": false,
    "email_sender": {
        "email": "fulano@domain.com",
        "id": id-do-remetente,
        "name": "Jonh Doe",
        "resource_uri": "/api/v1/campaigns/sender/id-do-remetente/"
    },
    "exclude_hard_bounced": false,
    "exclude_lists": [],
    "id": id-do-item-da-regua-de-campanha,
    "interval_period": "day",
    "interval_value": 0,
    "limit_to": null,
    "lists": [],
    "name": "Passo 1",
    "open_lists": [],
    "reply_call_to_action": "",
    "reply_contact_text": "",
    "reply_mobile_number": "",
    "reply_to": "",
    "resource_uri": "/api/v1/campaigns/rule_item/id-do-item-da-regua-de-campanha/",
    "rule": {
        "end_date": "2018-04-30T00:00:00",
        "id": id-da-regua-de-campanha,
        "name": "Teste",
        "pause_on_error": false,
        "resource_uri": "/api/v1/campaigns/rule/id-da-regua-de-campanha/",
        "send_remaining": false,
        "start_date": "2018-04-09T00:00:00",
        "status": "draft"
    },
    "sending_type": "email",
    "subject": "teste",
    "template": {
        "content": "",
        "date_created": "2020-10-21",
        "id": id-do-template,
        "last_updated": "2020-10-23",
        "name": "Curso Tributação das Cooperativas",
        "resource_uri": ""
    },
    "time": "09:00:00",
    "use_my_number": false
}

Passo 4 - Listando Itens de uma Régua de Campanha

Para visualizar todas os itens de uma Régua de Campanha, você deverá utilzar o método abaixo

GET: /api/v1/campaigns/rule_item/?rule=id-da-regua-de-campanha

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/campaigns/rule_item/?rule=id-da-regua-de-campanha

O resultado será semelhante a esse:

{
    "meta": {
        "limit": 50,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "click_lists": [],
            "create_dyn_list_from_clicks": false,
            "create_dyn_list_from_not_clicks": false,
            "create_dyn_list_from_not_in_rule": false,
            "create_dyn_list_from_not_opens": false,
            "create_dyn_list_from_not_previous_campaigns": false,
            "create_dyn_list_from_opens": false,
            "create_dyn_list_from_previous_campaigns": false,
            "email_sender": {
                "email": "fulano@domain.com",
                "id": id-do-remetente,
                "name": "Jonh Doe",
                "resource_uri": "/api/v1/campaigns/sender/id-do-remetente/"
            },
            "exclude_hard_bounced": false,
            "exclude_lists": [],
            "id": id-do-item-da-regua-de-campanha,
            "interval_period": "day",
            "interval_value": 0,
            "limit_to": null,
            "lists": [
                {
                    "contacts_hard_bounce": 0,
                    "contacts_soft_bounce": 0,
                    "contacts_valids": 1,
                    "id": id-da-lista,
                    "name": "Stormers",
                    "resource_uri": "",
                    "total_contacts": 1
                }
            ],
            "name": "Passo 1",
            "open_lists": [],
            "reply_call_to_action": "",
            "reply_contact_text": "",
            "reply_mobile_number": "",
            "reply_to": "",
            "resource_uri": "/api/v1/campaigns/rule_item/id-do-item-da-regua-de-campanha/",
            "rule": {
                "end_date": "2018-04-30T00:00:00",
                "id": id-da-regua-de-campanha,
                "name": "Teste",
                "pause_on_error": false,
                "resource_uri": "/api/v1/campaigns/rule/id-da-regua-de-campanha/",
                "send_remaining": false,
                "start_date": "2018-04-09T00:00:00",
                "status": "draft"
            },
            "sending_type": "email",
            "subject": "teste",
            "template": {
                "content": "",
                "date_created": "2020-10-21",
                "id": id-do-template,
                "last_updated": "2020-10-23",
                "name": "Curso Tributação das Cooperativas",
                "resource_uri": ""
            },
            "time": "09:00:00",
            "use_my_number": false
        }
        ...
    ]
}

Passo 5 - Editando um Item de Régua de Campanha

Você pode necessitar alterar um item da Régua de Campanha como por exemplo o intervalo de tempo, nesse caso você utilizar o método PATCH para o valor que você deseja alterar, conforme exemplo abaixo:

PATCH: /api/v1/campaigns/rule_item/XXX58/

data = {
   "name": "Passo 0",
   "sending_type" : "email",
   "lists": ["/api/v1/contacts/static_list/11597/"]
}

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X PATCH --data data https://painel.mailerweb.com.br/api/v1/campaigns/rule_item/XXX58/ 

Será retornado o objeto com os novos valores informados.

Passo 6 - Excluindo um Item de uma Régua de Campanha 

Você poderá excluir um Item de Régua de Campanha, conforme exemplo a seguir

DELETE: /api/v1/campaigns/rule_item/id-do-item-da-regua-de-campanha/

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X DELETE https://painel.mailerweb.com.br/api/v1/campaigns/rule_item/id-do-item-da-regua-de-campanha/

IMPORTANTE: As campanhas executadas e programadas por esse item NAO serão excluidas.

Passo 7 - Habilitando uma Régua de Campanha para Envio

Após você incluir os Itens de uma Régua de Campanha, as campanhas somente serão criadas, quando você habilitar a Régua. Para isso será necessário fazer uma chamada do tipo PATCH, atualizando o atributo status do objeto Régua de Campanha:

PATCH: /api/v1/campaigns/rule/id-da-regua-de-campanha/

data = {
   "status": "enabled"
}

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X PATCH --data data https://painel.mailerweb.com.br/api/v1/campaigns/rule/id-da-regua-de-campanha/ 

Após essa chamada, a Régua de Campanha, criará a primeira campanha conforme os itens criados.

Passo 8 - Colocando uma Régua de Campanha em Modo Rascunho

Você poderá pausar uma régua de campanha a qualquer tempo. Para isso será necessário fazer uma chamada do tipo PATCH, atualizando o atributo status do objeto Régua de Campanha:

PATCH: /api/v1/campaigns/rule/id-da-regua-de-campanha/

data = {
   "status": "draft"
}

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X PATCH --data data https://painel.mailerweb.com.br/api/v1/campaigns/rule/id-da-regua-de-campanha/ 

Após essa chamada, a Régua de Campanha, criará a primeira campanha conforme os itens criados.

Passo 9 - Excluindo uma Régua de Campanha

Você poderá excluir uma Régua de Campanha, conforme exemplo a seguir:

DELETE: /api/v1/campaigns/rule/id-da-regua-de-campanha/

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X DELETE https://painel.mailerweb.com.br//api/v1/campaigns/rule/id-da-regua-de-campanha/