# 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:

- `200 OK` – Indica que a resposta foi entregue com sucesso. Contudo, o sucesso da ação é indicado pelo atributo `status` no corpo da resposta.
- `301 Moved Permanently` ou `308 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:

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-header-exemplo-x-ser"><thead><tr><th width="60%">Header</th><th width="40%">Exemplo</th></tr></thead><tbody><tr><td><span class="paramTable__name">X-Server-API-Key</span>  
<span class="paramTable__description">Token da API associado ao seu servidor.</span></td><td>f29a45f0d4e1744ebaee</td></tr></tbody></table>

## Erros de Autenticação

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

<table border="1" cellpadding="5" cellspacing="0" class="table errorsTable" id="bkmrk-erro-atributos-inval"><thead><tr><th width="60%">Erro</th><th width="40%">Atributos</th></tr></thead><tbody><tr><td><span class="paramTable__name">InvalidServerAPIKey</span>  
A chave de API enviada no header `X-Server-API-Key` é inválida.</td><td>- token
    
    A chave de API consultada.

</td></tr><tr><td><span class="paramTable__name">ServerSuspended</span>  
O servidor de e-mail autenticado foi suspenso e não pode realizar operações.</td><td> </td></tr></tbody></table>

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

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

```bash
-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

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-par%C3%A2metro-tipo-valor"><thead><tr><th width="40%">Parâmetro</th><th width="20%">Tipo</th><th width="20%">Valor Padrão</th><th width="20%">Obrigatório</th></tr></thead><tbody><tr><td><span class="paramTable__name">id</span>

O ID da mensagem

</td><td>Integer</td><td>null</td><td>Sim</td></tr></tbody></table>

## Erros

<table border="1" cellpadding="5" cellspacing="0" class="table errorsTable" id="bkmrk-erro-atributos-messa"><thead><tr><th width="50%">Erro</th><th width="50%">Atributos</th></tr></thead><tbody><tr><td><span class="paramTable__name">MessageNotFound</span>

Nenhuma mensagem encontrada com o ID fornecido

</td><td>- id
    
    O ID da mensagem buscada

</td></tr></tbody></table>

## 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

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-atributo-tipo-exempl"><thead><tr><th width="35%">Atributo</th><th width="25%">Tipo</th><th width="40%">Exemplo</th></tr></thead><tbody><tr><td><span class="paramTable__name">id</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">token</span></td><td> </td><td> </td></tr></tbody></table>

### 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.

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-expans%C3%A3o-tipo-descri"><thead><tr><th width="35%">Expansão</th><th width="25%">Tipo</th><th width="40%">Descrição</th></tr></thead><tbody><tr><td><span class="paramTable__name">status</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">details</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">inspection</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">plain\_body</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">html\_body</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">attachments</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">headers</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">raw\_message</span></td><td> </td><td> </td></tr></tbody></table>

## 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.

```bash
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`:

```bash
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

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-par%C3%A2metro-tipo-valor"><thead><tr><th width="40%">Parâmetro</th><th width="20%">Tipo</th><th width="20%">Valor Padrão</th><th width="20%">Obrigatório</th></tr></thead><tbody><tr><td><span class="paramTable__name">id</span>

O ID da mensagem

</td><td>Integer</td><td>null</td><td>Sim</td></tr></tbody></table>

## Erros

<table border="1" cellpadding="5" cellspacing="0" class="table errorsTable" id="bkmrk-erro-atributos-messa"><thead><tr><th width="50%">Erro</th><th width="50%">Atributos</th></tr></thead><tbody><tr><td><span class="paramTable__name">MessageNotFound</span>

Nenhuma mensagem encontrada com o ID fornecido

</td><td>- id
    
    O ID da mensagem buscada

</td></tr></tbody></table>

## 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

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-atributo-tipo-exempl"><thead><tr><th width="35%">Atributo</th><th width="25%">Tipo</th><th width="40%">Exemplo</th></tr></thead><tbody><tr><td><span class="paramTable__name">id</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">status</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">details</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">output</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">sent\_with\_ssl</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">log\_id</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">time</span></td><td> </td><td> </td></tr><tr><td><span class="paramTable__name">timestamp</span></td><td> </td><td> </td></tr></tbody></table>

## Exemplo: Listar entregas de uma mensagem

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

```bash
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

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-par%C3%A2metro-tipo-valor"><thead><tr><th width="40%">Parâmetro</th><th width="20%">Tipo</th><th width="20%">Valor Padrão</th><th width="20%">Descrição</th></tr></thead><tbody><tr><td><span class="paramTable__name">to</span></td><td>Array</td><td>null</td><td>Endereços de e-mail dos destinatários (máximo de 50).</td></tr><tr><td><span class="paramTable__name">cc</span></td><td>Array</td><td>null</td><td>Endereços de e-mail de cópia (máximo de 50).</td></tr><tr><td><span class="paramTable__name">bcc</span></td><td>Array</td><td>null</td><td>Endereços de e-mail em cópia oculta (máximo de 50).</td></tr><tr><td><span class="paramTable__name">from</span></td><td>String</td><td>null</td><td>Endereço de e-mail para o cabeçalho "From".</td></tr><tr><td><span class="paramTable__name">sender</span></td><td>String</td><td>null</td><td>Endereço de e-mail para o cabeçalho "Sender".</td></tr><tr><td><span class="paramTable__name">subject</span></td><td>String</td><td>null</td><td>Assunto do e-mail.</td></tr><tr><td><span class="paramTable__name">tag</span></td><td>String</td><td>null</td><td>Tag identificadora do e-mail.</td></tr><tr><td><span class="paramTable__name">reply\_to</span></td><td>String</td><td>null</td><td>Endereço de resposta (Reply-To).</td></tr><tr><td><span class="paramTable__name">plain\_body</span></td><td>String</td><td>null</td><td>Corpo do e-mail em texto puro.</td></tr><tr><td><span class="paramTable__name">html\_body</span></td><td>String</td><td>null</td><td>Corpo do e-mail em HTML.</td></tr><tr><td><span class="paramTable__name">attachments</span></td><td>Array</td><td>null</td><td>Lista de anexos a serem enviados com o e-mail.</td></tr><tr><td><span class="paramTable__name">headers</span></td><td>Hash</td><td>null</td><td>Hash de cabeçalhos adicionais personalizados.</td></tr><tr><td><span class="paramTable__name">bounce</span></td><td>Boolean</td><td>null</td><td>Indica se a mensagem é uma notificação de erro (bounce).</td></tr></tbody></table>

## Erros

<table border="1" cellpadding="5" cellspacing="0" class="table errorsTable" id="bkmrk-erro-atributos-valid"><thead><tr><th width="60%">Erro</th><th width="40%">Atributos</th></tr></thead><tbody><tr><td><span class="paramTable__name">ValidationError</span>  
Os dados fornecidos não foram suficientes para envio.</td><td>- errors
    
    Hash com detalhes dos campos inválidos.

</td></tr><tr><td><span class="paramTable__name">NoRecipients</span>  
Nenhum destinatário foi definido para a mensagem.</td><td> </td></tr><tr><td><span class="paramTable__name">NoContent</span>  
O conteúdo da mensagem está ausente.</td><td> </td></tr><tr><td><span class="paramTable__name">TooManyToAddresses</span>  
Limite máximo de destinatários "To" atingido (máx. 50).</td><td> </td></tr><tr><td><span class="paramTable__name">TooManyCCAddresses</span>  
Limite máximo de endereços "CC" atingido (máx. 50).</td><td> </td></tr><tr><td><span class="paramTable__name">TooManyBCCAddresses</span>  
Limite máximo de endereços "BCC" atingido (máx. 50).</td><td> </td></tr><tr><td><span class="paramTable__name">FromAddressMissing</span>  
O endereço "From" é obrigatório e está ausente.</td><td> </td></tr><tr><td><span class="paramTable__name">UnauthenticatedFromAddress</span>  
O endereço "From" não está autorizado neste servidor.</td><td> </td></tr><tr><td><span class="paramTable__name">AttachmentMissingName</span>  
Um dos anexos está sem nome definido.</td><td> </td></tr><tr><td><span class="paramTable__name">AttachmentMissingData</span>  
Um dos anexos está sem dados definidos.</td><td> </td></tr></tbody></table>

## 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`.

```bash
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

<table border="1" cellpadding="5" cellspacing="0" class="table paramTable" id="bkmrk-par%C3%A2metro-tipo-valor"><thead><tr><th width="40%">Parâmetro</th><th width="20%">Tipo</th><th width="20%">Valor Padrão</th><th width="20%">Descrição</th></tr></thead><tbody><tr><td><span class="paramTable__name">mail\_from</span></td><td>String</td><td>null</td><td>Endereço que será registrado como remetente da mensagem.</td></tr><tr><td><span class="paramTable__name">rcpt\_to</span></td><td>Array</td><td>null</td><td>Lista de endereços de e-mail para os quais a mensagem será enviada.</td></tr><tr><td><span class="paramTable__name">data</span></td><td>String</td><td>null</td><td>Mensagem completa no formato RFC2822, codificada em base64.</td></tr><tr><td><span class="paramTable__name">bounce</span></td><td>Boolean</td><td>null</td><td>(Opicional) Define se a mensagem enviada é uma notificação de erro (bounce).</td></tr></tbody></table>

## Erros

<table border="1" cellpadding="5" cellspacing="0" class="table errorsTable" id="bkmrk-erro-atributos-unaut"><thead><tr><th width="60%">Erro</th><th width="40%">Atributos</th></tr></thead><tbody><tr><td><span class="paramTable__name">UnauthenticatedFromAddress</span>  
O endereço "From" não está autorizado para envio a partir deste servidor.</td><td> </td></tr></tbody></table>

## 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`.

```bash
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
  }'

```