Email API Web Service

Versão: 4.00 Última Atualização: 13/10/2015


Índice

  1. Introdução
  2. Enviando mensagens via Email
  3. Obtendo os eventos do Email

1. Introdução

Seguindo a documentação presente nesta página, você irá conseguir integrar o seu sistema com o Gateway de Email do MobiPronto! Para começar de pé direito, sugerimos que você leia os requerimentos, as notas importantes (onde comunicamos novidades e mudanças futuras) e as descrições de cada método. Desta forma, você irá ganhar tempo e conhecer a solução como um todo. Em caso de dúvida, estamos aqui para ajudá-lo! Acesse sua conta, crie um ticket de suporte e entre em contato conosco. Divirta-se integrando!

1.1. Requerimentos

É necessário ter acesso a "Credencial" e "Token" da sua conta para realizar a integração. Estes dados podem ser encontrados no menu de "Configurações", opção "Dados de Integração".

1.2. URL do Web Service

http://www.mpgateway-mail.com/ws/service.asmx

1.3. Notas importantes

1 A próxima versão irá conter as seguintes funcionalidades:

  • Consulta por intervalo de data
  • Consulta de saldo de créditos

2. Enviando mensagens via Email

O MPG_Send_Email é o método que permite o envio de mensagens via email através do nosso Gateway.

2.1. Método MPG_Send_Email

Parâmetros Requerido? Formato Descrição
PARAMETERS_FORMAT Sim A(3) Formato do parâmetro. Deve ser TXT
PARAMETERS Sim A(N) String com campos separados por | (barra vertical, pipe)

2.2. Descrição do PARAMETERS

Este parâmetro é uma string que contém os seguintes campos abaixo, separados por pipe (|)

Campos Requerido? Formato Descrição
VERSAO Sim A(4) Versão do PARAMETERS (atual é 4.00)
CREDENCIAL Sim A(40) Credencial da sua conta no MobiPronto
TOKEN Sim A(6) Código de acesso ao Gateway
PRINCIPAL_USER Não A(50) ou ""
Controle interno do cliente
METHOD Sim   Apenas WEBAPI
AUX_USER Não A(20) O valor atribuído a este parâmetro pode ser utilizado como referência em filtros, facilitando a identificação de mensagens específicas em relatórios criados por você a partir da plataforma
EMAIL_FROM Sim   Email do remetente 
NAME_FROM Não ≤ 100
Nome do remetente
EMAIL_TO Sim   Email do destinatário
NAME_TO Não  ≤ 100
Nome do destinatário
SUBJECT Não ≤ 200  Título do email
BODY_TYPE Sim    Informar o tipo do email. Colocar "TXT" ou "HTML"
BODY Sim ≤ 100000
Corpo do email. Necessário passar com encode. URL Encoding converte caracteres para um formato que pode ser transmitido pela Internet.

2.3. Retornos do MPG_Send_Email

Código de Retorno Descrição
000 Na fila para envio | ID da mensagem com M+39 posições
001 Credencial inválida
005 EMAIL_FROM com formato inválido
006 EMAIL_TO com formato inválido
008 BODY ultrapassou o número máximo de posições
009 Créditos insuficientes em conta 
010 Gateway bloqueado
013 BODY com conteúdo vazio ou inválido
015 Gateway sem operação. Favor, entrar em contato com o suporte
018 EMAIL_TO descadastrado
019 TOKEN inválido
020 BODY_TYPE inválido
021 Versão descontinuada ou inválida
022 Parâmetro(s) com formato inválido
023 Parâmetro(s) com formato inválido para esta versão
024 Parâmetro(s) inválido
025 Método inválido
800 a 899 Falha no Gateway. Favor, entrar em contato com o suporte
900 Erro de autenticação ou limite de segurança excedido
901 a 999 Erro interno. Favor, entrar em contato com o suporte

2.4. Exemplo

  • VB.NET
Imports Namespace_Webservices_Email
 
Partial Class _Default
    Inherits System.Web.UI.Page
 
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        Dim v_st_Status As String = String.Empty
        Dim v_st_Ret As String = String.Empty
        Dim v_st_Param As String = String.Empty
        ' ------------------------------
        ' Instanciando a Classe de Email
        ' ------------------------------
        Dim v_obj_Gateway As New MPGatewayEmail
        Dim v_st_Assunto As String = String.Empty
        Dim v_st_Corpo As String = String.Empty
        '
        v_st_Assunto = "Assunto"
       v_st_Corpo = System.Web.HttpUtillity.UrlDecode("Corpo do Email")
        v_st_Param = "4.00|CREDENCIAL|TOKEN||WEBAPI|Aux_User|abc@mobipronto.com|Nome FROM|abc@outlook.com||" & v_st_Assunto & "|HTML|" & v_st_Corpo        
	v_st_Ret = v_obj_Gateway.MPG_Send_Email("TXT", v_st_Param)
        '
        Response.Write(v_st_Ret)
    End Sub
End Class

3. Obtendo os eventos do Email

O MPG_ID_Email_Events é o método que retorna os eventos de um email.

3.1. Método MPG_ID_Email_Events

Parâmetros Requerido? Formato Descrição
PARAMETERS_FORMAT Sim A(3) Formato do parâmetro. Deve ser TXT
PARAMETERS Sim A(N) String com campos separados por | (barra vertical, pipe)

3.2. Descrição do PARAMETERS

Este parâmetro é uma string que contém os seguintes campos abaixo, separados por pipe (|)

Campos Requerido? Formato Descrição
VERSAO Sim A(4) Versão do PARAMETERS (atual é 4.00)
CREDENCIAL Sim A(40) Credencial da sua conta no MobiPronto
TOKEN Sim A(6) Código de acesso ao Gateway
ID_EMAIL Sim A(40)
Identificador do Email

3.3. Retornos do MPG_ID_Email_Events (JSON)

Com erro. Exemplo: { “error” : “019” }

{ "error":"$error" }

Código de Retorno Descrição
001 Credencial inválida
010 Gateway bloqueado
019 TOKEN inválido
021 Versão descontinuada ou inválida
022 Parâmetro(s) com formato inválido
023 Parâmetro(s) com formato inválido para esta versão
024 Parâmetro(s) inválido
026 ID de Email não encontrado ou não é desta conta.
800 a 899 Falha no Gateway. Favor, entrar em contato com o suporte
900 Erro de autenticação ou limite de segurança excedido
901 a 999 Erro interno. Favor, entrar em contato com o suporte

Retorno dos eventos

      { 
          "events": [ 
              { 
                 "code" : "xxxxx",
                 "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxx", 
                 "date_event": "YYYY-MM-DD HH:MM:SS",  
                 "event_description": "xxxxxxxxxxxxxxxxxxxx..." 
     
              }, 
              { 
                 "code" : "xxxxx",
                 "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxx", 
                 "date_event": "YYYY-MM-DD HH:MM:SS", 
                 "event_description": "xxxxxxxxxxxxxxxxxxxx..." 
              } 
          ] 
      }

3.4. Status de Retorno do Email

Código e Nome Descrição
PROC-Processed Email recebido pelo nosso servidor e pronto para realizar o envio
DROP-Dropped Destinatário com email inválido, descadastrado (opt-out) ou com bloqueio permanente
DELIV-Delivered Email aceito pelo servidor do destinatário
BHARD-Bounce Hard Email do destinatário inexistente ou com bloqueio permanente
OPEN-Open Destinatário abriu o email 
CLICK-Click Destinatário abriu e clicou em um hyperlink contido no email
SPAM-Spamreport Servidor do destinatário ou destinatário marcou email como spam
UNSUB-Unsubscribe Email descadastrado
DEFER-Deferred Email em fila do servidor do destinatário
BSOFT-Bounce Soft Email do destinatário com quota excedida, offline ou com bloqueio temporário

3.5. Exemplo em VB.NET

Imports Namespace_Webservices_Email
 
Partial Class _Default
    Inherits System.Web.UI.Page
 
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        Dim v_st_Status As String = String.Empty
        Dim v_st_Ret As String = String.Empty
        Dim v_st_Param As String = String.Empty
        ' ------------------------------
        ' Instanciando a Classe de Email
        ' ------------------------------
        Dim v_obj_Gateway As New MPGatewayEmail
        Dim v_st_Assunto As String = String.Empty
        Dim v_st_Corpo As String = String.Empty
        '
        v_st_Assunto = "Assunto"
         v_st_Corpo = System.Web.HttpUtillity.UrlDecode("Corpo do Email") v_st_Param = "4.00|CREDENCIAL|TOKEN||WEBAPI|Aux_User|abc@mobipronto.com|Nome FROM|abc@outlook.com||" & v_st_Assunto & "|HTML|" & v_st_Corpo        
	v_st_Ret = v_obj_Gateway.MPG_Send_Email("TXT", v_st_Param)
        '
        Response.Write(v_st_Ret)
    End Sub
End Class