API Sender25


API Sender25

Através desta API, você pode enviar, consultar, listar o envio de mensagens de email.

Como Interagir com a API

Nossa API opera sobre o protocolo HTTPS e utiliza o formato JSON para troca de informações. Todas as requisições devem ser enviadas para https://br-app.sender25.com e requerem a inclusão do header de autenticação X-Server-API-Key com sua chave de API.

As requisições podem ser feitas utilizando métodos HTTP como GET e POST. Geralmente, as requisições que modificam o estado (como enviar) devem utilizar o método POST , com os parâmetros passados no corpo da requisição em formato JSON.

Recebendo Respostas

Todas as respostas da API são retornadas em formato JSON. Independentemente do resultado, você receberá uma estrutura padrão que se assemelha ao exemplo abaixo:

{
  "status": "success",       /* "success", "parameter-error" ou "error" */
  "time": 0.123,             /* Tempo de processamento no servidor */
  "flags": {                 /* Informações adicionais, como dados de paginação */
    /* ... */
  },
  "data": {                  /* Resultado da requisição ou detalhes do erro */
    /* ... */
  }
}

Status: O atributo status indica se a operação foi realizada com sucesso (success), se houve erro nos parâmetros (parameter-error) ou se ocorreu algum erro não categorizado (error).

Time: O atributo time informa quanto tempo a requisição levou para ser processada no servidor.

Flags: O atributo flags contém informações adicionais sobre a requisição, como detalhes de paginação quando aplicável.

Data: O atributo data possui os resultados da ação solicitada ou detalhes dos erros ocorridos.

Sobre os Códigos HTTP

A API Sender25 utiliza os códigos de status HTTP de forma complementar. Embora a resposta padrão sempre retorne o corpo com o atributo status, os seguintes códigos HTTP podem ser observados:

Se precisar de ajuda ou tiver dúvidas, entre em contato com nossa equipe. Estamos prontos para auxiliá-lo na integração e uso da API Sender25.

Autenticação do Servidor (Server Authenticator)

Para utilizar a API do Sender25, é necessário autenticar suas requisições utilizando uma chave de API específica do servidor. Essa autenticação é feita por meio de headers HTTP padrão incluídos em cada requisição.

Headers de Autenticação

O seguinte header deve ser enviado em todas as requisições para autenticar seu servidor:

Header Exemplo
X-Server-API-Key
Token da API associado ao seu servidor.		 f29a45f0d4e1744ebaee

Erros de Autenticação

Os erros abaixo podem ser retornados caso haja falhas na verificação da chave de autenticação.

Erro Atributos
InvalidServerAPIKey
A chave de API enviada no header X-Server-API-Key é inválida.

  • token

    A chave de API consultada.
ServerSuspended
O servidor de e-mail autenticado foi suspenso e não pode realizar operações.		  

Autenticação com X-Server-API-Key

Todas as requisições à API devem conter o header X-Server-API-Key, conforme mostrado abaixo:

-H "X-Server-API-Key: SUA_CHAVE_AQUI"

Substitua SUA_CHAVE_AQUI pela chave fornecida para seu servidor no painel do Sender25.

Retornar detalhes da mensagem

Este endpoint retorna todos os detalhes disponíveis sobre uma mensagem específica.

URL

/api/v1/messages/message

Acesso

Deve ser autenticado como servidor utilizando o header X-Server-API-Key. Caso não seja autorizado, será retornado um erro do tipo AccessDenied.

Parâmetros

Parâmetro Tipo Valor Padrão Obrigatório

id

O ID da mensagem

 Integer null Sim

Erros

Erro Atributos

MessageNotFound

Nenhuma mensagem encontrada com o ID fornecido

  • id

    O ID da mensagem buscada

Dados da Resposta

Esta ação retorna uma estrutura de mensagem, contendo os dados básicos. Por padrão, não são retornadas expansões. Para obter dados adicionais, envie o parâmetro _expansions com os nomes das expansões desejadas ou true para todas.

Message Structure

Atributos Básicos

Atributo Tipo Exemplo
id    
token    

Expansões Disponíveis

Expansões são estruturas aninhadas de outros objetos relacionados à mensagem. Por padrão, nenhuma expansão é retornada, mas você pode usar o parâmetro _expansions para incluí-las.

Expansão Tipo Descrição
status    
details    
inspection    
plain_body    
html_body    
attachments    
headers    
raw_message    

Exemplo: Buscar detalhes de uma mensagem com expansões

Este exemplo mostra como solicitar dados adicionais da mensagem utilizando o parâmetro _expansions. Você pode passar uma lista com os campos desejados ou true para expandir tudo.

curl -X POST https://br-app.sender25.com/api/v1/messages/message \
  -H "Content-Type: application/json" \
  -H "X-Server-API-Key: SUA_CHAVE_AQUI" \
  -d '{
    "id": 12345,
    "_expansions": ["status", "plain_body", "html_body", "attachments", "headers"]
  }'

Se quiser retornar todas as expansões disponíveis, utilize "_expansions": true:

curl -X POST https://br-app.sender25.com/api/v1/messages/message \
  -H "Content-Type: application/json" \
  -H "X-Server-API-Key: SUA_CHAVE_AQUI" \
  -d '{
    "id": 12345,
    "_expansions": true
  }'

Retornar entregas de uma mensagem

Este endpoint retorna um array contendo todas as tentativas de entrega realizadas para uma mensagem específica.

URL

/api/v1/messages/deliveries

Acesso

Deve ser autenticado como servidor utilizando o header X-Server-API-Key. Se não for autorizado, será retornado um erro do tipo AccessDenied.

Parâmetros

Parâmetro Tipo Valor Padrão Obrigatório

id

O ID da mensagem

 Integer null Sim

Erros

Erro Atributos

MessageNotFound

Nenhuma mensagem encontrada com o ID fornecido

  • id

    O ID da mensagem buscada

Dados da Resposta

Esta ação retorna uma estrutura de entrega (Delivery Structure) contendo os atributos básicos e estendidos relacionados às tentativas de entrega da mensagem.

Delivery Structure

Atributos Básicos

Atributo Tipo Exemplo
id    
status    
details    
output    
sent_with_ssl    
log_id    
time    
timestamp    

Exemplo: Listar entregas de uma mensagem

Esse exemplo mostra como consultar as tentativas de entrega associadas a uma mensagem específica.

curl -X POST https://br-app.sender25.com/api/v1/messages/deliveries \
  -H "Content-Type: application/json" \
  -H "X-Server-API-Key: SUA_CHAVE_AQUI" \
  -d '{
    "id": 12345
  }'

Enviar uma mensagem

Esta ação permite o envio de uma nova mensagem, bastando fornecer os parâmetros adequados.

URL

/api/v1/send/message

Acesso

É necessário autenticar-se como um servidor utilizando o header X-Server-API-Key. Se não for autorizado, será retornado um erro do tipo AccessDenied.

Parâmetros

Parâmetro Tipo Valor Padrão Descrição
to Array null Endereços de e-mail dos destinatários (máximo de 50).
cc Array null Endereços de e-mail de cópia (máximo de 50).
bcc Array null Endereços de e-mail em cópia oculta (máximo de 50).
from String null Endereço de e-mail para o cabeçalho "From".
sender String null Endereço de e-mail para o cabeçalho "Sender".
subject String null Assunto do e-mail.
tag String null Tag identificadora do e-mail.
reply_to String null Endereço de resposta (Reply-To).
plain_body String null Corpo do e-mail em texto puro.
html_body String null Corpo do e-mail em HTML.
attachments Array null Lista de anexos a serem enviados com o e-mail.
headers Hash null Hash de cabeçalhos adicionais personalizados.
bounce Boolean null Indica se a mensagem é uma notificação de erro (bounce).

Erros

Erro Atributos
ValidationError
Os dados fornecidos não foram suficientes para envio.

  • errors

    Hash com detalhes dos campos inválidos.
NoRecipients
Nenhum destinatário foi definido para a mensagem.		  
NoContent
O conteúdo da mensagem está ausente.		  
TooManyToAddresses
Limite máximo de destinatários "To" atingido (máx. 50).		  
TooManyCCAddresses
Limite máximo de endereços "CC" atingido (máx. 50).		  
TooManyBCCAddresses
Limite máximo de endereços "BCC" atingido (máx. 50).		  
FromAddressMissing
O endereço "From" é obrigatório e está ausente.		  
UnauthenticatedFromAddress
O endereço "From" não está autorizado neste servidor.		  
AttachmentMissingName
Um dos anexos está sem nome definido.		  
AttachmentMissingData
Um dos anexos está sem dados definidos.		  

Dados da Resposta

Esta ação retorna um Hash com os dados da mensagem enviada.

Exemplo: Envio de mensagem padrão (JSON)

Este exemplo mostra como enviar uma mensagem utilizando corpo em texto simples e HTML, com o endpoint /api/v1/send/message.

curl -X POST https://br-app.sender25.com/api/v1/send/message \
  -H "Content-Type: application/json" \
  -H "X-Server-API-Key: SUA_CHAVE_AQUI" \
  -d '{
    "to": ["destinatario@exemplo.com"],
    "from": "remetente@seudominio.com",
    "subject": "Assunto do e-mail",
    "plain_body": "Texto simples do corpo",
    "html_body": "HTML do corpo"
  }'

Enviar mensagem em formato RAW (RFC2822)

Este endpoint permite o envio de uma mensagem bruta no formato RFC2822, juntamente com os destinatários. É similar ao envio via SMTP tradicional.

URL

/api/v1/send/raw

Acesso

A requisição deve ser autenticada como um servidor, utilizando o header X-Server-API-Key.
Caso contrário, será retornado um erro do tipo AccessDenied.

Nova PáginaParâmetros

Parâmetro Tipo Valor Padrão Descrição
mail_from String null Endereço que será registrado como remetente da mensagem.
rcpt_to Array null Lista de endereços de e-mail para os quais a mensagem será enviada.
data String null Mensagem completa no formato RFC2822, codificada em base64.
bounce Boolean null (Opicional) Define se a mensagem enviada é uma notificação de erro (bounce).

Erros

Erro Atributos
UnauthenticatedFromAddress
O endereço "From" não está autorizado para envio a partir deste servidor.		  

Dados da Resposta

Esta ação retorna um objeto (Hash) contendo as informações resultantes do envio.

Exemplo: Envio de mensagem no formato RAW (RFC2822)

Este exemplo demonstra como enviar uma mensagem no formato RFC2822 base64 com o endpoint /api/v1/send/raw.

curl -X POST https://br-app.sender25.com/api/v1/send/raw \
  -H "Content-Type: application/json" \
  -H "X-Server-API-Key: SUA_CHAVE_AQUI" \
  -d '{
    "mail_from": "remetente@seudominio.com",
    "rcpt_to": ["destinatario@exemplo.com"],
    "data": "Q29udGVudG8gZW0gYmFzZTY0IGRlIHVtYSBtZW5zYWdlIFJGQzI4MjIuLi4=",
    "bounce": false
  }'