Mail API

IntroduçãoLast update: 2022-11-29

Web Api responsável por receber o malling a ser enviado via e-mail, salvar as informações em base de dados e direcionar o mesmo para o envio. Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como configurar e realizar o envio de email.

Esta documentação tem como objetivo instruir sobre a utilização da mesma, demonstrando como realizar o envio de e-mails.

URL API:
  • URL:https://apisms.code7.com/Mail

API

Documentação de Uso da API de Mail.

Login

Token de Acesso - Metodo de Login


Para utilizar os Micro Serviços Code7, é necessário um Login/ Senha fornecido pela equipa de TI. Ao realizar a validação de Login, em caso de positivo o mesmo gera um token de acesso, os login são de uso restrito e podem ser usados para todos os Micro Serviços na qual ele tem acesso.

Todas as requisições POST - Json para o API devem conter o campo de token no primeiro campo do JSON (com exceção dos métodos de Login/ Consulta Token). Todas as requisições GET - Json para o API devem conter o campo de token na URL de solicitação (com exceção dos métodos de Login/ Consulta Token).

Warning

O token de acesso tem validade de 6 horas, após esta validade, o CRM deve logar novamente para gerar um novo Token.


Método de utilização:

POST - https://apisms.code7.com/Mail/Login


JSON:

Exemplo de JSON de Login, substitua as informações abaixo por suas credenciais.

 
                                    {
                                        "login": "code7.xyz",
                                        "password": "12345678"
                                    }

Envio de Mail – Post

Metodo de Send


Método utilizado para enviar o maling de dados dos e-mails. O mailing deve ser enviado através de um POST na API, utilizando o método API/MAIL, o mesmo deve enviar um arquivo JSON (conforme exemplo abaixo), onde deve conter um ou mais clientes para envio.

Método utilizado para enviar e-mail.


Método de utilização:

POST - https://apisms.code7.com/Mail/Send

Orientação de Uso

Para envios em massa, utilizar somente até no máximo 1000 registros por POST, para Lotes maiores, quebrar o lote de envio em duas ou mais postagens de 1000 conforme a quantidade que deseja enviar.


Dicionário de dados:
Campo Tipo Descrição Obrigatório Tamnaho
lote_name string Nome da lote listada no método Get da api.
5000
token string Token de retorno obtido após o Login na Api.
8
nome string Nome do destinatário.
5000
email string E-mail do destinatário.
5000
id_identifier string Identificador do email.
100
subject string Assunto do email.
5000
reply_to string E-mail de resposta.
5000
from_email string E-mail do remetente.
5000
from_name string Nome do remetente.
5000
idMedia string Id do anexo obtido no momento do Upload da Media.
100
field01 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field02 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field03 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field04 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field05 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field06 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field07 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field08 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field09 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field10 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field11 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field12 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field13 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field14 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field15 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field16 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field17 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field18 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field19 string Campo destinado à substituição de valores no corpo do e-mail.
5000
field20 string Campo destinado à substituição de valores no corpo do e-mail.
5000

Atenção

A falta de um ou mais campos Obrigatórios pode ocasionar a recusa do Email por parte do Provedor, atente-se que todos estão sendo preenchidos.

JSON:

Exemplo de JSON de Envio, substitua as informações abaixo de token pelo token obtido no Login.


                [
                        {
                            "lote_name": "Teste Envio",
                            "token": "xyza1234",
                            "nome": "TESTE 1",
                            "email": "joao.teste@code7.com",
                            "id_identifier": "abc123",
                            "subject": "Teste Micro Servico",
                            "reply_to": "noreply@teste.com",
                            "from_email": "contato@teste.com",
                            "from_name": "Teste Inc.",
                            "field01": "Sistemas Ltda.",
                            "field02": "11-99999999",
                            "idMedia": "23f1ca09-6606-45"
                        }
                ]

Consulta Lote

Metodo de Consulta


O método API/LOTE através de um GET da API, retorna as lotes cadastradas.

Warning

O campo lote_name deve conter a descrição da lote e o campo html_path deve conter o link de template cadastrado.


Método de utilização:

GET - https://apisms.code7.com/Mail/Lote/token


Dicionário de dados:
Campo Tipo Descrição
codMailLote string Id de identicação da lote criada.
descMailLote string Descrição da lote criada.
html_path string Link do template cadastrado.
linkCallbackStatus string URL do Webhook cadastrado.
JSON:

Exemplo do JSon de retorno.


                 [
                     {
                         "codMailLote": 1,
                         "descMailLote": "Teste Envio",
                         "html_path": "https://portal/html_composer/templates/24901.html",
                         "linkCallbackStatus": "https://webhook/retorno/status"
                     }
                 ]

Grava Novo Lote

Metodo de Lote


Método utilizado para salvar novas lotes na base de dados.

O html_path deve ser composto por um link de acesso a uma estrutura html, na qual será enviada por email. Dentro da estrutura os campos field01 a field20 devem ser especificados entre duas chaves {{field01}}, assim os mesmo serão substituídos ao envio do email.

Warning

Os campos que conterem no template, devem ser enviados no maling. Exemplo de template: http://url/template/index.html.

Os campos utilizados estão descritos abaixo.


Método de utilização:

POST - https://apisms.code7.com/Mail/Lote


Dicionário de dados:
Campo Tipo Descrição
descMailLote string Descrição da lote.
token string Token de retorno obtido após o Login na Api.
html_path string Link do template cadastrado.
linkCallbackStatus string URL do Webhook para receber os Status.
JSON:

Exemplo de JSON de Lote, substitua as informações abaixo de token pelo token obtido no Login.


                   [
                       {
                           "token": "sdsd1234",
                           "descMailLote": "Teste Cadastro",
                           "html_path": "https://portal/html_composer/templates/24901.html",
                           "linkCallbackStatus": "https://webhook/retorno/status"
                       }
                   ]

Consulta Malling Enviado

Metodo de Consulta


O método API/RETORNO através de um GET da API, retorna os status de cada e-mail contido no malling, assim é possível verificar se o e-mail foi enviado com sucesso, se o destinatário leu o mesmo a data de envio e recebimento.

Os campos utilizados estão descritos abaixo.


Método de utilização:

GET - https://apisms.code7.com/Mail/Retorno/token/idlote


Dicionário de dados:
Campo Tipo Descrição
id_identifier string Id de identicação do maling.
dataEnvio dateTime Data na qual o e-mail foi enviado.
dataEvento dateTime Data na qual o evento foi ocorrido.
nomeEvento string Tipo de Evento ocorrido com o e-mail.
descricaoEvento string Descrição do tipo de Evento.
razaoEvento string Motivo na qual este evento ocorreu.
JSON:

Exemplo do JSon de Retorno.


                  [
                      {
                          "codMailRetorno": 1,
                          "codMailLote": 2,
                          "codMailEnvio": 1,
                          "id_Identifier": "teste02",
                          "dataEnvio": "2018-01-26T13:41:14.72",
                          "dataEvento": "2018-02-01T14:07:09",
                          "nomeEvento": "bounce",
                          "descricaoEvento": "Falha no envio",
                          "razaoEvento": "O endereço da caixa de emails especificada não existe"
                      }
                  ]

Upload de medias

Metodo de Upload


Método utilizado para realizar o upload de medias.

Warning

Para o tipo de media document serão aceitos arquivos doc, docx, ppt, pptx, xls, xlsx e pdf. Para o tipo image serão aceitos arquivos jpeg, png, gif, bmp e webp. Para o tipo audio, serão aceitos os arquivos AAC, M4A, AMR, MP3, OGG e OPUS. Os arquivos terão validade de até 30 dias.


Método de utilização:

POST - https://apisms.code7.com/Mail/UploadFile


Exemplo de utilização:

Content-Type : multipart/form-data File : (seu arquivo)


Dicionário de dados:
Campo Tipo Descrição Parâmetro Obrigatório
File form-data Arquivo de media para realizar upload. form-data
JSON:

Exemplo do JSon de retorno.


                    {
                            "idMedia": "xyzxyx-xyz",
                            "validUntil": "2018-09-30"
                    }

Webhook

As atualizações são enviadas através de Webhook.

Após criar o hook e enviar sua URL de Webhook as funcionalidades de callback estão ativas.

Webhook Status

Callback Status


Para identificar o retorno do status, é necessário criar um webhook e configra no lote (Campo: linkCallbackStatus), assim o mesmo iria enviar o retorno da mensagem quando um evento acontece através de um JSon.


Dicionário de dados:
Campo Tipo Descrição
id string ID único de identificação.
email string Email na qual refere-se o status.
id_identifier string ID de identificação postado no momento do Envio.
lote_name string Lote na qual refere-se o status.
Date string Data do evento.
status string Status de envio.
type string Tipo do status envida.
JSON:

Exemplo do JSon de status Mail.


                           {
                               "id": "PfSwrD5dQ_S0qpv7yBvp1Q",
                               "email": "teste@code7.com",
                               "id_identifier": "000142547",
                               "lote_name": "EnvioCode7_XYZ",
                               "Date": "2019-05-17 19:38:26",
                               "status": "delivered",
                               "type": "WhatsappStatus"
                           }