API Sender25
- API Sender25
- Autenticação do Servidor (Server Authenticator)
- Retornar detalhes da mensagem
- Retornar entregas de uma mensagem
- Enviar uma mensagem
- Enviar mensagem em formato RAW (RFC2822)
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:
200 OK
– Indica que a resposta foi entregue com sucesso. Contudo, o sucesso da ação é indicado pelo atributostatus
no corpo da resposta.301 Moved Permanently
ou308 Permanent Redirect
– Indica que a requisição deve ser enviada para outra URL, normalmente devido à exigência de utilizar o protocolo HTTPS.500 Internal Server Error
– Erro interno no servidor. Caso ocorra, reporte o problema à equipe de suporte.503 Service Unavailable
– A API está indisponível, possivelmente por manutenção ou problemas temporários.
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. |
|
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 |
|
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 |
|
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. |
|
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
}'