Ajuda

Você poderá criar e validar os domínios de envios de suas campanhas de e-mail marketing utilizando a nossa API de gestão de contatos e campanhas, utilize os métodos abaixo para começar a criar e validar seus domínios de envio. Eles são importantes tê-los pois garantem que as mensagens serão entregues com autenticidade no domínio, mitigando a probabilidade de sua campanha ser tratada como SPAM.

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 um Domínio de Envio

Com esse método você poderá criar os domínios de envios de e-mail marketing. Informações sobre os domínios de envio poderão ser vistas em "Como incluir as entradas de DNS do domínio de envio?"

Para interagir com os domínios de envio vamos criar o objeto com os seguintes parâmetros e com o seguinte endpoint:

• Campo "domain_name" é utilizado apenas para identificar o domínio de envio 'exemplo.com.br'
• Campo "click_domain_name" informa qual é o endpoint do rastreamento de cliques para o domínio 'exemplo.com.br', a informação desse campo deverá ser inserido no seu DNS, apontando no formato como segue:
   

• Campo "click_domain_verified", booleano, informa se o domínio foi validado ou não pelo sistema, verificando se no DNS já foram aplicadas as configurações (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA)
• Campo "mx_domain_name" informa que é o endpoint para recebimento dos retornos das mensagens enviadas, a informação desse campo deverá ser inserido no seu DNS, apontando no formato como segue:
   

• Campo "mx_domain_verified_verified", booleano, informa se o mx do domínio foi validado ou não pelo sistema, verificando se no DNS já foram aplicadas as configurações (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA)
• Campo "spf_domain_name" informa que é o endpoint para autenticação do envio de mensagens, a informação desse campo deverá ser inserido no seu DNS, apontando no formato como segue:
   

• Campo "spf_domain_verified_verified", booleano, informa se o spf do domínio foi validado ou não pelo sistema, verificando se no DNS já foram aplicadas as configurações (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA)
• Campo "is_blacklisted", booleano, verifica se o domínio está listado em alguma blacklist. Para consulta quais blacklist, você deverá acessar o painel de controle.
• Campo "verification_auth_token", campo do tipo texto, informa o valor que deverá ser aplicado para autenticar o domínio para envio pela Amazon Web Services, nosso provedor de infraestrutura. A autenticação vem no formato:

"verification_auth_token": [
  {
     "name": "_amazonses",
     "status": "Failed",
     "type": "TXT",
     "value": "HxchTralsO....."
  }
]

• Campo "name" informa o endpoint que deverá ser cadastro no seu DNS, do tipo TXT (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA)
• Campo "status" informa se já houve a validação da entrada do domínio junto a Amazon Web Services (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA).
• Campo "type" informa o tipo de entrada que deverá ser cadastrada no DNS (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA).
• Campo "value" informa o valor da entrada que deverá ser incluída no seu DNS, para autenticação do serviço (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA).

Por fim, no objeto principal, ainda tempos:

• ID, do tipo inteiro que informa o ID do domínio - (NAO DEVE SER ENVIADO NO POST - SOMENTE LEITURA)

POST: /api/v1/configuration/domain/

data = {
    "domain_name": "exemplo.com.br",
}

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/configuration/domain/

O resultado esperado será semelhante ao JSON abaixo:

{
            "click_domain_name": "click.dominio.com.br",
            "click_domain_verified": true,
            "customers": [
                "/api/v1/customers/customer/id-do-cliente/"
            ],
            "date_created": "2017-12-16",
            "domain_name": "dominio.com.br",
            "id": id-do-dominio,
            "is_blacklisted": false,
            "last_updated": "2021-02-27",
            "mx_domain_name": "msg.dominio.com.br",
            "mx_verified": true,
            "resource_uri": "/api/v1/configuration/domain/id-do-dominio/",
            "spf_domain_name": "29d0431b31d49a.....spf.mlwbx.com",
            "spf_domain_verified": true,
            "verification_auth_token": [
                {
                    "name": "_amazonses",
                    "status": "Failed",
                    "type": "TXT",
                    "value": "HxchTralsOfYMzYPUiRMOC......"
                }
            ]
}

Repare que o Código do Domínio está no atributo ID e no atributo resource_url, onde você poderá acessar os detalhes desse domínio 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 domínios você poderá fazer a partir desse ID.

Agora que você está de posse do ID do Domínio de Envio, vamos ao Passo 2:

Passo 2 - Listando os Domínios de Envio da Minha Conta

Para visualizar todas as campanhas de envio de SMS marketing 

GET: /api/v1/configuration/domain/

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

O resultado será semelhante a esse

{
    "meta": {
        "limit": 50,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 16
    },
    "objects": [
        {
            "click_domain_name": "click.dominio.com.br",
            "click_domain_verified": true,
            "customers": [
                "/api/v1/customers/customer/id-do-cliente/"
            ],
            "date_created": "2017-12-16",
            "domain_name": "dominio.com.br",
            "id": id-do-dominio,
            "is_blacklisted": false,
            "last_updated": "2021-02-27",
            "mx_domain_name": "msg.dominio.com.br",
            "mx_verified": true,
            "resource_uri": "/api/v1/configuration/domain/id-do-dominio/",
            "spf_domain_name": "29d0431b31d49a.....spf.mlwbx.com",
            "spf_domain_verified": true,
            "verification_auth_token": [
                {
                    "name": "_amazonses",
                    "status": "Failed",
                    "type": "TXT",
                    "value": "HxchTralsOfYMzYPUiRMOC......"
                }
            ]
        },
   ]
}

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 Dominio:

GET: /api/v1/configuration/domain/?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/configuration/domain/?id=xxx

Listando os modelos por nome:

GET: /api/v1/configuration/domain/?domain_name=dominio.com.br

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/configuration/domain/?domain_name=dominio.com.br

Passo 3 - Obtendo a chave DKIM de um Domínio de Envio

Para ter acesso as chaves DKIM de um domínio você deverá acessar o Método DKIM a partir do ID do domínio conforme exemplo:

GET: /api/v1/configuration/domain/dkim/XXX58/

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:api_key"\ -X GET https://painel.mailerweb.com.br//api/v1/configuration/domain/dkim/XXX58/

O resultado será semelhante a esse

[
    {
        "endpoint": "ce675f0046c6c1785....h.dkim.mlwbx.com",
        "selector": "ce675f0046c6c1785....h"
    },
    {
        "endpoint": "aqxkwmpxwuvlwzly3....z.dkim.amazonses.com",
        "selector": "aqxkwmpxwuvlwzly3....z"
    },
    {
        "endpoint": "2i2owvwlmo27onso......d.dkim.amazonses.com",
        "selector": "2i2owvwlmo27onso....d"
    },
    {
        "endpoint": "ec7fkqian6bdnptlk....a.dkim.amazonses.com",
        "selector": "ec7fkqian6bdnptlk....a"
    }
]

Este método retorna as entradas que você deve colocar no DNS do seu domínio, no provedor de hospedagem, conforme exemplo abaixo:

Passo 4 - Solicitando a validação do Domínio de Envio

Um vez que já foi configurou no DNS do seu provedor de hospedagem do seu domínio, você agora pode solicitar que o sistema verifique se as configurações foram realizadas corretamente:

Para ter acesso ao serviço de validação, você deverá chamar o endpoint conforme exemplo abaixo:

GET: /api/v1/configuration/domain/validate/XXX58/

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:api_key"\ -X GET https://painel.mailerweb.com.br/api/v1/configuration/domain/validate/XXX58/

O resultado será semelhante a:

{
    "click_domain_verified": true,
    "dkim_verified": true,
    "domain_name": "dominio.com.br",
    "id": id-dominio
    "mx_verified": true,
    "spf_domain_verified": true
}

O resultado acima informa que o domínio está todo validado, pois todos os atributos estão marcados como "true", se um desses estiver como "false" o domínio não está validado para envio.

Passo 5 - Excluindo o Domínio de Envio

Para excluir um domínio de envio a partir de seu ID, basta chamar:

DELETE: /api/v1/configuration/domain/XXX58/

curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:api_key"\ -X DELETE https://painel.mailerweb.com.br/api/v1/configuration/domain/XXX58/

A API retornará 204 e o registro foi excluído com sucesso, caso não retornará como 401 - Forbidden.