Ajuda

Você poderá criar campanhas de e-mail marketing de forma programática utilizando a nossa API de gestão de contatos e campanhas, utilize os métodos abaixo para começar a criar conteúdo em nossa plataforma de envio de e-mail marketing,

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 Campanha de Envio de E-mail Marketing

Com esse método você poderá programar sua campanha e e-mail marketing, mas antes você precisará criar os remetentes de envio e como criar o modelo de e-mail para envio. Informações poderão ser vistas em e "Como criar um remetente para Envio de E-mail Marketing utilizando a API da MailerWeb" e "Como criar um Modelo de Envio de E-mail Marketing utilizando a API da MailerWeb".

Para interagir com as campanhas de E-mail Marketing, vamos criar o objeto com os seguintes parâmetros e com o seguinte endpoint:

• Campo "name" é utilizado apenas para identificar a nome da campanha, não será exibido ao destinatário
• Campo "sender" é utilizado para você designar o remetente que será utilizado nessa mensagem, ele deve ser um e-mail autenticado e configurado. Ao criar o remetente, o sistema vai enviar automaticamente uma mensagem solicitando a confirmação por meio de clique em um link, caso você já tenha configurado os domínios de envio através de autenticação por chave DKIM, SPF e DMARC essa autenticação não será mais realizada.
• 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 "email_template" é utilizado para designar qual o modelo de e-mail você deverá utilizar para enviar essa campanha.
• 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" é utilizado para adicionar o contato a uma ou mais listas caso ele abra a campanha de e-mail marketing.
• Campo "click_lists" é utilizado para adicionar o contato a uma ou mais listas caslo ele clique na campanha de e-mail marketing.
• Campo "date_scheduled" é utilizado para definir a programação da campanha, deverá ser no formado YYYY-MM-DD HH:MM.
• Campo "exclude_hard_bounced" é 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" é 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.

POST: /api/v1/campaigns/email_campaign/

{
    "name": "Teste 01",
    "sender": "/api/v1/campaigns/sender/id-do-remetente/",
    "reply_to": null,
    "email_template": "/api/v1/campaigns/email_template/id-do-modelo-de-email/",
    "lists": ["/api/v1/contacts/static_list/id-da-lista-1/", "/api/v1/contacts/static_list/id-da-lista-2/"],
    "exclude_lists": [],
    "open_lists": [],
    "click_lists": [],
    "date_scheduled": "2021-03-15 16:00",
    "exclude_hard_bounced": true,
    "subject": null
}

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/email_campaign/ 

O resultado esperado será semelhante ao JSON abaixo:

{
    "click_lists": [],
    "clicked": 0,
    "complaint": 0,
    "current_item": null,
    "date_created": "2021-01-20T17:36:53",
    "date_finished": null,
    "date_scheduled": "2021-03-15T16:43:01",
    "date_started": null,
    "description": null,
    "email_template": {
        "date_created": "2014-07-15",
        "html_body_description": "Teste",
	"id": id-email-template,
        "last_updated": "2014-07-15",
        "name": "Teste",
        "resource_uri": "/api/v1/campaigns/email_template/id-email-template/",
        "subject": "Isso é um teste"
    },
    "error": 0,
    "exclude_hard_bounced": true,
    "exclude_lists": [],
    "id": 112376,
    "last_updated": "2021-01-20T17:36:53",
    "limit_to": null,
    "lists": [],
    "message": "Teste",
    "name": "Teste 01",
    "open_lists": [],
    "opt_out": 0,
    "read": 0,
    "reply_to": null,
    "resource_uri": "/api/v1/campaigns/email_campaign/id-da-campanha/",
    "send_remaining": false,
    "sender": {
        "email": "seu@dominio.com.br",
        "id": id-do-remetente,
        "name": "Mailerweb",
        "resource_uri": "/api/v1/campaigns/sender/id-do-remetente/"
    },
    "status": "waiting",
    "subject": "Isso é um teste",
    "success": 0,
    "total_queued": 0,
    "total_scheduled": 0,
    "total_sent": 0,
    "unique_read": 0
}

Repare que o ID da Campanha de Envio de E-mail Marketing 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.

Agora que você está de posse do ID da da Campanha de Envio de E-mail Marketing, vamos ao Passo 2:

Passo 2 - Listando as Campanhas de E-mail Marketing existentes

Para visualizar todas as campanhas de envio de e-mail marketing 

GET: /api/v1/campaigns/email_campaign/

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

O resultado será semelhante a esse

{
    "meta": {
        "limit": 50,
        "next": "/api/v1/campaigns/email_campaign/?status=finished&limit=50&offset=50",
        "offset": 0,
        "previous": null,
        "total_count": 287
    },
    "objects": [
        {
            "click_lists": [],
            "clicked": 2,
            "complaint": 0,
            "current_item": null,
            "date_created": "2014-07-15T16:43:01",
            "date_finished": "2014-07-15T16:45:00",
            "date_scheduled": "2014-07-15T16:43:01",
            "date_started": "2014-07-15T16:43:01",
            "description": null,
            "email_template": {
                "date_created": "2014-07-15",
                "html_body_description" : "Isso é um teste",
                "id": id-email-template,
                "last_updated": "2014-07-15",
                "name": "Teste",
                "resource_uri": "/api/v1/campaigns/email_template/id-email-template/",
                "subject": "O teste"
            },
            "error": 12,
            "exclude_hard_bounced": true,
            "exclude_lists": [],
            "id": 4368,
            "last_updated": "2014-07-15T22:12:57",
            "limit_to": null,
            "lists": [
                {
                    "contacts_hard_bounce": 0,
                    "contacts_soft_bounce": 0,
                    "contacts_valids": 1,
                    "date_created": "2015-06-23",
                    "id": id-da-lista,
                    "last_updated": "2020-11-11",
                    "name": "Stormers",
                    "total_contacts": 1
                }
            ],
            "message":  "Isso é um teste",
            "name": "Teste 01",
            "open_lists": [],
            "opt_out": 0,
            "read": 10,
            "reply_to": null,
            "resource_uri": "/api/v1/campaigns/email_campaign/id-da-campanha/",
            "send_remaining": false,
            "sender": {
                "email": "exemplo@dominio.com.br",
                "id": id-remetente,
                "name": "Exemplo",
                "resource_uri": "/api/v1/campaigns/sender/id-remetente/"
            },
            "status": "finished",
            "subject": null,
            "success": 11,
            "total_queued": 23,
            "total_scheduled": 23,
            "total_sent": 23,
            "unique_read": 0
        },
        ...
    ]
}

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 os modelos por ID da Campanha:

GET: /api/v1/campaigns/email_campaign/?id=xxx

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

Listando os modelos por nome:

GET: /api/v1/campaigns/email_campaign/?name=teste

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

Listando os modelos por status da campanha:

GET: /api/v1/campaigns/email_campaign/?status=progress

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

Os status disponíveis para consulta são:

STATUS_CHOICES = (
        ('counting', _('Contando os Contatos')),
        ('processing', _('Processando Contatos')),
        ('moderating', _('Em Moderação')),
        ('waiting', _('Programada')),
        ('progress', _('Enviando')),
        ('finished', _('Finalizada')),
        ('paused', _('Pausada')),
        ('suspended', _('Interrompida')),
        ('canceled', _('Cancelada')),
)

Passo 3 - Atualizando uma Campanha de Envio de E-mail Marketing

Você pode necessitar alterar um item da campanha de envio de e-mail marketing como por exemplo a data de envio, nesse caso você utilizar o método PATCH com os parâmetros abaixo:

PATCH: /api/v1/campaigns/email_campaign/XXX58/

data = {
   'date_scheduled': '2021-03-15 00:40'
}

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/email_campaign/XXX58/ 

IMPORTANTE: Somente campanhas que estiverem programadas ou em andamento poderão ser atualizados, os demais estados não permite a atualização da campanha. Você poderá alterar o status da campanha, desde que ela não tenha sido finalizada, suspensa ou cancelada.

Agora você poderá criar campanhas, obter relatórios de dados em tempo real em sua aplicação.