Introdução
Bem-vindo à API do envie.email! Aqui você encontrará os endpoints necessários para integrar rapidamente sua aplicação.
Para turbinar, além da documentação RESTful, disponibilizamos também alguns exemplos em JSON no painel. Para trocar a linguagem de programação (se disponível), basta clicar nas abas painel.
Caso seja cliente e ainda não possua os tokens de autenticação de API, solicite aqui. Dúvidas? Entre em contato conosco.
Autenticação
É necessário estar autenticado para poder usar a API. Passe os tokens public-key e private-key no cabeçalho.
Para utilizar a API do envie.email é necessário autenticar. A autenticação é realizada através dos tokens public-key e private-key, passados via Header. Nossa API requer que todas as requisições contenham os tokens no cabeçalho, conforme exemplo abaixo:
public-key: XXXXXXXXXXXXXXXXXXXX
private-key: XXXXXXXXXXXXXXXXXXXX
Caso já seja cliente e ainda não tenha seus tokens, solicite através do nosso SAC.
Listas
Cria uma nova lista
Estrutura JSON a ser enviada:
{
"general": {
"name": "string",
"description": "string"
}
}
Estrutura JSON de confirmaçãoa a ser retornada:
{
"status": "string",
"list_uid": "string"
}
HTTP Request
POST /lists/create
Estrutura para criar uma lista de emails:
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| name | Nome da lista a ser criada | Sim |
| description | Descrição da lista a ser criada | Sim |
Recebe dados uma lista
Estrutura JSON a ser enviada:
{
"list": "string"
}
Estrutura JSON da lista a ser retornada:
{
"status": "string",
"data": {
"record": {
"general": {
"list_uid": "string",
"name": "string",
"display_name": "string",
"description": "string"
},
"defaults": {
"from_name": "string",
"reply_to": "string",
"subject": "string"
},
"notifications": {
"subscribe": "string",
"unsubscribe": "string",
"subscribe_to": "string",
"unsubscribe_to": "string"
},
"company": {
"name": "string",
"address_1": "string",
"address_2": "string",
"zone_name": "string",
"city": "string",
"zip_code": "string",
"address_format": "string",
"country": {
"country_id": "string",
"name": "string",
"code": "string"
},
"zone": {
"zone_id": "string",
"name": "string",
"code": "string"
}
}
}
}
}
HTTP Request
POST /lists/get
Estrutura para receber dados uma lista específica de emails:
{
"list": "string"
}
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| list | UID da lista | Sim |
Receba informações de Listas
Estrutura JSON a ser retornada:
{
"status": "string",
"data": {
"count": "string",
"total_pages": 0,
"current_page": 0,
"next_page": 0,
"records": [
{
"general": {
"list_uid": "string",
"name": "string",
"display_name": "string",
"description": "string"
},
"defaults": {
"from_name": "string",
"reply_to": "string",
"subject": "string"
},
"notifications": {
"subscribe": "string",
"unsubscribe": "string",
"subscribe_to": "string",
"unsubscribe_to": "string"
},
"company": {
"name": "string",
"address_1": "string",
"address_2": "string",
"zone_name": "string",
"city": "string",
"zip_code": "string",
"address_format": "string",
"country": {
"country_id": "string",
"name": "string",
"code": "string"
},
"zone": {
"zone_id": "string",
"name": "string",
"code": "string"
}
}
}
]
}
}
Endpoint para receber informações de listas.
HTTP Request
GET /lists/show
Recebe uma lista específica
Estrutura JSON a ser retornada:
{
"status": "string",
"data": {
"count": "string",
"total_pages": 0,
"current_page": 0,
"records": [
{
"subscriber_uid": "string",
"EMAIL": "string",
"FNAME": "string",
"LNAME": "string",
"status": "string",
"source": "string",
"ip_address": "string",
"date_added": "string"
}
]
}
}
Parâmetros POST
| Opcional | Descrição |
|---|---|
| UID | UID da lista (composto por letras e números). |
Transacionais
Envio
Exemplo de estrutura JSON para envio transacional:
{
"to_name": "string",
"to_email": "string",
"from_name": "string",
"from_email": "string",
"reply_to_name": "string",
"reply_to_email": "string",
"subject": "string",
"body": "string",
"plain_text": "string",
"attachments": [
{
"data": "string",
"name": "string",
"mime": "string"
}
]
}
POST /singlesending/create
Estrutura para envio de email transacional:
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| to_name | Nome do destinatário | Sim |
| to_email | E-mail do destinatário | Sim |
| from_name | Nome do remetente | Sim |
| from_email | E-mail do remetente | Sim |
| reply_to_name | Nome do endereço de resposta | Sim |
| reply_to_email | E-mail de resposta | Sim |
| subject | Assunto | Sim |
| body | Mensagem, aceita marcações HTML | Sim |
| plain_text | Se não preenchido, o texto puro será gerado automaticamente | Não |
| attachments | Array com dados de anexos | Não |
Anexos
Estrutura de anexos (attachments):
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| data | arquivo codificado em base64 | Sim |
| name | nome do arquivo a ser salvo sem a extensão (a extensão será adicionada automaticamente de acordo com o MIME type). Não se pode repetir no mesmo email | Sim |
| mime | MIME Type do arquivo | Sim |
MIME Types
Por padrão os seguintes MIME Types são aceitos,isso quer dizer que se um outro tipo de MIME Type for utilizado, a requisição não será completada com sucesso. Caso precise utilizar um outro tipo de arquivo (MIME Type), entre em contato com o nosso suporte para habilitarmos.
| MIME Type | Tipo de Arquivo |
|---|---|
| application/pdf | |
| application/zip | .zip |
| text/plain | .txt |
| application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| application/excel | .xls |
| image/jpeg | .jpg |
| image/png | .png |
Webhooks
Abertura de Mensagem
Callback acionado quando há abertura da mensagem. Para o funcionamento, é obrigatório que a mensagem esteja em formato HTML entre as devidas tags <html><body></body></html>.
Se durante o post o callback receber um status diferente de 200, duas novas tentativas serão feitas.
Existem dois timestamp. O primeiro carrega o horário que ocorreu o evento de abertura e deverá ser considerado. O segundo, dentro de payload=>message carrega o horário que o e-mail foi enviado.
Estrutura JSON que será enviada:
{
"event": "MessageLoaded",
"timestamp": 0,
"payload": {
"ip_address": "string",
"user_agent": "string",
"message": {
"id": 0,
"to": "string",
"from": "string",
"timestamp": 0,
"tag": "string"
}
}
}
Cliques em Links
Callback acionado quando há cliques em links. Para o funcionamento, é obrigatório que a mensagem esteja em formato HTML entre as devidas tags <html><body></body></html>.
Existem dois timestamp. O primeiro carrega o horário que ocorreu o evento de abertura e deverá ser considerado. O segundo, dentro de payload=>message carrega o horário que o e-mail foi enviado.
Estrutura JSON que será enviada:
{
"event": "MessageLinkClicked",
"timestamp": 0,
"payload": {
"user_agent": "string",
"url": "string",
"token": "string",
"ip_address": "string",
"user_agent": "string",
"message": {
"id": 0,
"to": "string",
"from": "string",
"timestamp": 0,
"tag": "string"
}
}
}
Enviado com Sucesso
Quando uma mensagem é entregue com sucesso ao destinatário.
Estrutura JSON que será enviada:
{
"event": "MessageSent",
"payload": {
"output": "string",
"details": "string",
"message": {
"id": 0,
"to": "string",
"from": "string",
"timestamp": 0,
"tag": "string"
}
}
}
Falha Temporária (Bounce)
Quando uma mensagem a ser entregue está atrasada pois a primeira tentativa foi falha. Será enviado um callback a cada nova tentativa de entrega.
Estrutura JSON que será enviada:
{
"event": "MessageDelayed",
"timestamp": 0,
"payload": {
"details": "string",
"output": "string",
"message": {
"id": 0,
"to": "string",
"timestamp": 0,
"tag": "string"
}
}
}
Falha Permanente (Bounce)
Quando uma mensagem a não pode ser entregue devido a um erro temporário do servidor de destino.
Estrutura JSON que será enviada:
{
"event": "MessageDeliveryFailed",
"timestamp": 0,
"payload": {
"details": "string",
"output": "string",
"message": {
"id": 0,
"to": "string",
"timestamp": 0,
"tag": "string"
}
}
}
Em Blacklist (Temporário)
Quando uma mensagem sofreu uma recusa temporária e está em fila aguardando novas tentativas.
Estrutura JSON que será enviada:
{
"event": "MessageHeld",
"timestamp": 0,
"payload": {
"details": "string",
"output": "string",
"message": {
"id": 0,
"to": "string",
"timestamp": 0,
"tag": "string"
}
}
}
Erros
Os seguintes erros podem ser retornados pela API:
| Código | Significado |
|---|---|
| 400 | Bad Request -- Sua requisição é inválida. |
| 401 | Unauthorized -- Sua chave API está errada. |
| 403 | Forbidden -- O acesso é restrito. |
| 404 | Not Found -- Endpoint não encontrado. |
| 405 | Method Not Allowed -- Método não permitido. |
| 406 | Not Acceptable -- O formato da requisição não é JSON. | 409 | Conflict -- Email em blacklist. |
| 429 | Too Many Requests -- Você excedeu a quantidade de requisições por segundo! |
| 500 | Internal Server Error -- Ocorreu um problema interno. Tente outra vez. |
| 503 | Service Unavailable -- Serviço temporariamente indisponível - tente mais tarde. |