API

Configure o IAGENTEsmtp em sua aplicação e, em menos de 5 minutos, envie e-mails diretamente de sua plataforma.

Apresentação

Se você possui uma aplicação, site ou qualquer serviço online, certamente possui algum processo automatizado que necessita do envio de e-mails, correto? Envio de cobranças, avisos e até mesmo comunicados simples aos seus clientes. Então: conheça o IAGENTEsmtp: plataforma para agilizar seu tráfego de envios de e-mails e análise de resultados.

Conectando no SMTP

Para conectar em seu servidor SMTP utilize as informações abaixo. Todos os emails devem ser enviados utilizando UTF-8.
  • host
  • usuario
  • senha
  • porta
  • smtp1.iagentesmtp.com.br
  • seu usuário de acesso no sistema
  • sua senha de acesso no sistema
  • 25 ou 587
* Limite de 2MB por cada mensagem enviada, incluindo cabeçalhos e anexos;
* Limite de 500 destinatários para cada mensagem enviada;
* Limite de 15 conexões simultâneas;
* Limite de 500 conexões por minuto;
* CC serão transformados em emails avulsos;
* BCC não serão enviados;
Parâmetros adicionais no cabeçalho dos emails enviados
Parâmetro
  • x-campanhaid
  • x-trackingdomain
Descrição
  • Especifica um identificador vinculado a seu email (nome de campanha ou id interno)
  • Ativa o monitoramento de cliques e leituras utilizando o domínio especificado. O domínio deve estar com regra de CNAME configurado.

Conectando no SMTP

Para conectar em seu servidor SMTP utilize as informações abaixo. Todos os emails devem ser enviados utilizando UTF-8.
  • host
  • usuario
  • senha
  • porta
  • smtp1.iagentesmtp.com.br
  • seu usuário de acesso no sistema
  • sua senha de acesso no sistema
  • 25 ou 587
* Limite de 2MB por cada mensagem enviada, incluindo cabeçalhos e anexos;
* Limite de 500 destinatários para cada mensagem enviada;
* Limite de 15 conexões simultâneas;
* Limite de 500 conexões por minuto;
* CC serão transformados em emails avulsos;
* BCC não serão enviados;
Parâmetros adicionais no cabeçalho dos emails enviados
Parâmetro
  • x-campanhaid
  • x-trackingdomain
Descrição
  • Especifica um identificador vinculado a seu email (nome de campanha ou id interno)
  • Ativa o monitoramento de cliques e leituras utilizando o domínio especificado. O domínio deve estar com regra de CNAME configurado.

Enviando por HTTP - POST

Sua chave para autenticação HTTP.
  • CHAVE
  • sua chave
As requisições devem ser realizadas para o endereço abaixo em UTF-8 e os valores dos parametros URLENCODED.
  • POST
  • DATA
  • iagentesmtp.com.br/api/v1/send.json (ou .xml)
api_user=seu_login&
api_key=sua_chave&
from=remetente@exemplo.com.br&
fromname=Nome_Remetente&
to=destinatario@exemplo.com.br&
toname=Nome_Destinatario&
subject=Assunto_Teste&
html=codigo_html
Resposta JSON em caso de sucesso.
{
"status": "OK",
"message": "1 mensagens processadas"
}
Resposta XML em caso de erro.
{
"status": "ERRO",
"message": "Falha autenticacao"
}
Resposta XML em caso de sucesso.
<result> <status>OK</status> <message>1 mensagens processadas</message> </result>
Resposta XML em caso de erro.
<result> <status>ERRO</status> <message>Falha autenticacao</message> </result>
Lista completa de parâmetros
Parâmetro
  • api_user
  • api_key
  • from
  • fromname
  • to
  • toname
  • subject
  • html
  • text
  • replyto
  • campanhaid
  • trackingdomain
Obrigatório
  • sim
  • sim
  • sim
  • não
  • sim
  • não
  • sim
  • não
  • não
  • não
  • não
  • não
Descrição
  • Login de sua conta
  • Chave de sua conta
  • Endereço de email do remetente da mensagem
  • Nome do remetente da mensagem em formato urlencoded
  • Endereço de email do destinatário da mensagem. Para múltiplos destinatários veja tabela abaixo.
  • Nome do destinatário da mensagem em formato urlencoded. Para múltiplos destinatários veja tabela abaixo.
  • Assunto de sua mensagem
  • Conteúdo HTML de sua mensagem em formato urlencoded. Se esse parâmetro for vazio o parâmetro "texto" deve ser informado.
  • Conteúdo TEXTO de sua mensagem em formato urlencoded. Se esse parâmetro for vazio o parâmetro "html" deve ser informado.
  • Especifica o endereço de resposta a mensagem enviada
  • Especifica um identificador seu a mensagem
  • Especifica o domínio a ser utilizado para captura de leituras, clicks e cancelamentos em suas mensagens.
    O domínio informado deve estar com CNAME configurado para funcionar corretamente.
Para enviar emails para múltiplos destinatários utilize os parâmetros "to" e "toname" em forma de array. (máximo 1000 destinatários por requisição)
  • POST
  • DATA
  • iagentesmtp.com.br/api/v1/send.json (ou .xml)
api_user=seu_login&
api_key=sua_chave&
from=remetente@exemplo.com.br&
fromname=Nome_Remetente&
to[]=destinatario1@exemplo.com.br&
to[]=destinatario2@exemplo.com.br&
to[]=destinatario3@exemplo.com.br&
toname[]=Nome_Destinatario_1&
toname[]=Nome_Destinatario_2&
toname[]=Nome_Destinatario_3&
subject=Assunto_Teste&
html=codigo_html

Melhorando a entregabilidade (SPF)

Para melhorar a entregabilidade de seus emails é necessário configurar o SPF no DNS de seus domínios (domínios que serão utilizados como remetente das mensagens).
Adicione o seguinte registro TXT no DNS de todos os seus domínios:
v=spf1 a mx include:_spf.localservices.com.br ~all
Se o registro já existir, adicione "include:_spf.localservices.com.br" antes do final, conforme exemplo:
v=spf1 a mx include:_spf.seudominio.com include:_spf.localservices.com.br ~all

Ativando relatórios de leituras, cliques e cancelamentos (CNAME)

Configurando CNAME

Para ativar os relatórios de cliques e leituras é necessário especificar e configurar um domínio de sua propriedade.

Crie um apontamento do tipo “CNAME" no DNS do domínio, conforme abaixo:
Tipo
  • CNAME
Host
  • app1
Valor
  • iagentesmtp.com.br
* Os relatórios só estão disponíveis para emails enviados no formato HTML.
* Para ativar o link de descadastramento em seus emails utilize Remover

Enviando notificações para sua aplicação (webhooks)

Para enviar notificações para sua aplicação é necessário informar um URL para onde devemos postar as informações.

Abaixo o exemplo de uma notificação enviada para sua aplicação (GET).
Abaixo o exemplo de uma notificação enviada para sua aplicação (GET).
http://www.seudominio.com.br/seuscript.php?Data=12/23/2015+12:23:33&
CampanhaID=1234&
Email=email@email.com.br&
Assunto=Asunto+do+envio&
Tipo=bounce&
Descricao=endereco+invalido
Parâmetros enviados em uma notificação
Parâmetro
  • Data
  • CampanhaID
  • Email
  • Tipo
  • Descricao
  • Assunto
Descrição
  • Data e hora em que o evento foi gerado
  • Retorna o valor informado por você no momento do envio
  • Endereço de email
  • Tipo do evento (ver tabela abaixo)
  • Detalhes do evento
  • Assunto do email
Tipo de notificações
Evento
  • bounce
  • leitura
  • clique
  • cancelamento
Descrição
  • Sempre que um email é rejeitado no provedor destino, informando caixa postal cheia, email inexistente etc...
  • Sempre que um destinatário confirma a leitura de um email enviado (visualizou imagens contidas na mensagem)
  • Sempre que uma url é clicada em um email
  • Sempre que um destinatário solicita não receber mais seus emails

Instanciando método SOAP

O consumo de métodos do WEBSERVICE IAGENTEsms deve ser feito através da URL:
https://www.iagentesms.com.br/webservices/ws.php
Para instanciar um método SOAP você pode utilizar a classe nativa do PHP SoapClient, ao qual necessita de 2 parâmetros: A URI do arquivo WSDL e um array de opções.

Como a API da IAGENTEsms não utiliza modo WSDL, então é necessário informar um array de opções.
$options = array(
'location' => 'https://www.iagentesms.com.br/webservices/ws.php',
'uri' => 'https://www.iagentesms.com.br/webservices/',
'encoding' => 'ISO-8859-1',
'trace' => 1,
'exceptions'=> 0 );
Este array de opções deve ser passada como parâmetro para a classe SoapClient e armazená-la em uma variável.
$ws = new SoapClient(NULL, $options);
Desta maneira você estará pronto para consumir todos os métodos disponíveis em nossa API.

Para saber sobre mais como funciona o SoapClient e o parâmetro WSDL acesse:
http://php.net/manual/pt_BR/soapclient.soapclient.php
http://fabriciosanchez.com.br/2/wsdl-o-que-e-pra-que-serve-onde-utilizo/

Autenticação

Todos os métodos do WEBSERVICE só devem ser invocados após autenticação da conta, que pode ser feita uma única vez a cada sessão.

Para realizar a autenticação de sua conta através do método SOAP, é necessário utilizar o método Auth().
Parâmetros obrigatórios:
Nome
  • Usuário
  • Senha
Tipo
  • String
  • String
Descrição
  • Seu usuário de acesso ao sistema
  • Sua senha de acesso ao sistema
Exemplo de invocação do método:
$ws->Auth("iagente","1234");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso

Consulta de saldo

Caso você possua sua conta na modalidade PRÉ-PAGA, é possível consultar o saldo da conta utilizando o método consulta_saldo().
Exemplo de invocação do método:
$ws->consulta_saldo();
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
http://www.seudominio.com.br/recebeSMS.php
Resposta a requisição consulta_saldo()
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem contendo saldo da conta

Criação de grupos

Para criar novos grupos em sua conta, utilize o método adicionar_grupo().
Parâmetros obrigatórios:
Nome
  • Grupo
Tipo
  • String
Descrição
  • Nome do grupo a ser criado
Exemplo de invocação do método:
$ws->adicionar_grupo("Novos clientes");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • ID do grupo na conta do cliente

Atualização de grupos

Para renomear um grupo é necessário utilizar o método atualizar_grupo().
Parâmetros obrigatórios
Nome
  • ID_GRUPO
  • Grupo
Tipo
  • Inteiro
  • String
Descrição
  • ID do grupo de sua conta
  • Novo nome do grupo
Exemplo de invocação do método:
$ws->atualizar_grupo("739", "Clientes antigos");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
http://www.seudominio.com.br/recebeSMS.php
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso

Listagem de grupos

Para listar todos os grupos de sua conta, utilize o método listar_grupos().
Exemplo de invocação do método:
$ws->listar_grupos();
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
Tipo
  • Matriz
Descrição
  • Matriz com informações dos grupos

Remover grupo

Para remover um grupo de sua conta, utilize o método remover_grupo().
Parâmetros obrigatórios:
Nome
  • ID_GRUPO
Tipo
  • Inteiro
Descrição
  • ID do grupo na conta do cliente
Exemplo de invocação do método:
$ws->remover_grupo("739");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso

Inserir contato no grupo

Para adicionar um contato a um grupo, utilize o método adicionar_contato().
Parâmetros disponíveis
Nome
  • Nome
  • Celular
  • ID_GRUPO
Tipo
  • String
  • Inteiro
  • Inteiro
Descrição
  • Nome do contato
  • Número de celular do contato, com DDD
  • ID do grupo em sua conta
Exemplo de invocação do método:
$ws->adicionar_contato("João","5199999999","739");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso

Remover contato do grupo

Para remover um contato de algum grupo, utilize o método remover_contato().
Parâmetros obrigatórios:
Nome
  • Celular
  • ID_GRUPO
Tipo
  • Inteiro
  • Inteiro
Descrição
  • Número de celular do contato com DDD
  • ID do grupo em sua conta
Exemplo de invocação do método:
$ws->remover_contato("5199999999","739");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso

Excluir contatos dos grupos

Para remover todos os contatos de um grupo, utilize o método limpar_grupo().
Parâmetros obrigatórios
Nome
  • ID_GRUPO
Tipo
  • Inteiro
Descrição
  • ID do grupo em sua conta
Exemplo de invocação do método:
$ws->limpar_grupo("739");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso

Envio de mensagem avulsa

Para enviar uma mensagem utilizando o método SOAP, utilize o método enviar_sms().
Parâmetros disponíveis
Nome
  • Método
  • Destinatário
  • Mensagem
  • Data
  • Código
Tipo
  • String
  • Inteiro
  • String
  • Data e Hora
  • Inteiro
Descrição
  • Método para envio avulso sempre será "avulso"
  • Número de destino com DDD
  • Mensagem com até 150 caracteres
  • Data do envio - opcional
  • Código interno do cliente para consulta de Postback - opcional
Exemplo de invocação do método:
$ws->enviar_sms("avulso", "5199999999", "Teste de SMS", "", "2034");
Apesar do parâmetro Código ser opcional vale lembrar que, caso não seja passado, futuramente não será possível realizar a consulta de status deste envio.

Após o envio da requisição, o IAGENTEsms devolverá uma respost a em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • ID do agendamento

Envio de mensagens em lote

Para enviar mensagens em lote, utilize o método enviar_lote().
Parâmetros disponíveis:
Nome
  • Método
  • Destinatários
  • Mensagem
  • Data
  • Código
Tipo
  • String
  • Array
  • String
  • Data e Hora
  • Inteiro
Descrição
  • Método para envio em lote sempre será "lote"
  • Números de destino com DDD
  • Mensagem com até 150 caracteres
  • Data do envio - opcional
  • Código interno de seu envio para consulta de Postback
Exemplo de invocação do método:
$ws->enviar_lote("lote", array("5199999999","5198888888","5197777777"), "Teste de SMS", "", "2034");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor(array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • ID do agendamento

Envio de mensagem para grupo

Para enviar mensagem para um grupo de sua conta, utilize o método enviar_sms_grupo().
Parâmetros disponíveis
Nome
  • Método
  • Grupo
  • Mensagem
  • Data
  • Código
Tipo
  • String
  • Inteiro
  • String
  • Data e Hora
  • Inteiro
Descrição
  • Método para envio em grupo sempre será "grupo"
  • ID do grupo em sua conta
  • Mensagem com até 150 caracteres
  • Data do envio - opcional
  • Código interno de seu envio para consulta de Postback
Exemplo de invocação do método:
$ws->enviar_sms_grupo("grupo", "739", "Teste de SMS", "", "1020");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • ID do agendamento

Consulta Status SMS: * Função disponível apenas para envio de SMS individuais

Para consultar o status de um SMS enviado, utilize o método verifica_status().
Parâmetros disponíveis
Nome
  • ID_AGENDAMENTO
Tipo
  • Inteiro
Descrição
  • ID do cliente informado na invocação do método enviar_sms().
Exemplo de invocação do método:
$ws->verifica_status("1020");
Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor(array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Status da mensagem
Códigos de retorno a sua requisição
Resposta
  • AGUARDANDO
  • ENVIADO
  • ENTREGUE
  • NAO SUPORTADA
  • NAO ENTREGAVEL
  • RECEBIDA
  • RESPOSTA
  • RECUSADA
  • FALHA OPERADORA
  • ERRO – descricao do erro
Tipo
  • Mensagem aguardando envio para operadora
  • Mensagem enviada para operadora
  • Mensagem entregue ao destinatário
  • Mensagem nao suportada na plataforma
  • Mensagem nao vai ser entregue ao destinatario
  • Mensagem recebida por shortcode e Keyword (MO)
  • Mensagem de resposta a uma mensagem previamente enviada (MO)
  • Mensagem recusada pela operadora
  • Falha de envio da mensagem na operadora
  • Mensagem de erro contendo descricao do erro ao lado

Call back de mensagens

A plataforma disponibiliza o envio automático de: ​

• Status de mensagens (todas as contas);
• Mensagens recebidas por keyword (canal corporativo);
• Respostas (canal corporativo).

Para receber essas informações em seu site ou sistema informe uma URL em seu painel web no menu "CONFIGURAÇÕES> INTEGRACAO" que deverá receber as requisições enviadas por nossa plataforma. Todas requisição são enviadas utilizando o método GET.
Exemplo de url para receber o call back:
http://www.seudominio.com.br/recebeSMS.php
Parâmetros enviados no Call Back de mensagens:
Parâmetro
  • codigosms
  • status
  • celular
  • shortcode
  • mensagem
Utilização
  • Envio de status
  • Envio de status
  • Recebimento de mensagem
  • Recebimento de mensagem
  • Recebimento de mensagem
Descrição
  • Identificador da mensagem em seu sistema
  • Texto com o status da mensagem (conforme códigos retorno envio de sms)
  • Número do celular que enviou a mensagem
  • Número shortcode que recebeu a mensagem
  • Resposta de um de seus destinatários a uma mensagem enviada