API

Este é o guia de como utilizar recursos do Mailtop através de sua API.

Autenticação

A autenticação é realizada via token privado, por cliente. Este token dá acesso a todos os recursos, por isso tenha cuidado: ele não deve ser compartilhado em hipótese alguma. Se você não lembrar do seu token, ou se você acha que ele foi comprometido de alguma forma, entre em contato conosco pelo e-mail suporte@mailtop.com.br.

O seu Token pode ser informado:

  • usando query string:
curl "https://api.mailtop.com.br/v1/campanhas?private_token=xxxxxxx"
  • ou usando o cabeçalho de requisição PRIVATE-TOKEN (maiúsculo e com o caractere -):
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://api.mailtop.com.br/v1/campanhas"

Você pode simular as requisições usando a interface da documentação interativa, ou usando os comandos cURL informados na documentação. Para mostrar o comando, acesse o endpoint desejado e clique em "Try it out", e depois em "Execute".

Limites

Para que possamos prover o melhor serviço possível, nós implementamos alguns limites para as conexões feitas. Um único endereço IP pode executar no máximo 1800 requisições a cada 2 minutos, para qualquer operação. Endereços que excederem este limite receberão um código HTTP 429 como resposta, junto com o cabeçalho X-RateLimit-Reset, que informa quando o bloqueio será removido.

Paginação

O controle de paginação é realizada com parâmetros via query string.

curl -X GET "https://api.mailtop.com.br/v1/campanhas/?page=1&per_page=200" -H  "PRIVATE-TOKEN: xxxxxxx"
  • page é utilizado para selecionar a página
  • per_page define a quantidade de registros a exibir por página

O valor padrão da quantidade exibida por página é de 1000. No cabeçalho da resposta é disponibilizado links para acessar a página anterior, próxima, primeira e última.

Tipos de Dados

Algumas informações na API (como os valores aceitos na segmentação) devem ser processadas de acordo com um tipo pré-estabelecido. Quando indicado, os tipos e formatos a usar devem ser estes:

Tipo Formato Observações
integer int32 inteiros de 32 bits
integer int64 inteiros de 64 bits
number float
number double
string
boolean
string date Formato full-date da RFC3339
string date-time Formato date-time da RFC3339

SSL

Nossos servidores liberam acesso a todos os métodos da API apenas via HTTPS, através de certificados válidos. Por isso, verifique se sua biblioteca de acesso consegue fazer requisições HTTP via SSL.

Documentação interativa

Utilize nossa documentação interativa para ter acesso a informações de todos os endpoints disponíveis na API. Veja quais são as informações necessárias para realizar requisições e quais são os possíveis retornos. Se você possuir os dados necessários para autenticar, através da documentação será possível consumir a API e realizar todas as operações disponíveis. Clique aqui para acessar.

Exemplo de Segmentação

Veja a implementação de referência da da interface para criação de novos Segmentos. Esta interface é criada através dos dados disponibilizados no endpoint GET /listas/{lista_id}/condicoes. Para acessar o exemplo clique aqui. Esta implementação utiliza apenas Javascript, sem nenhuma dependência externa. O código-fonte pode ser utilizado de acordo com a sua necessidade.

Alterações na API

A versão da API é que define todo o comportamento da API que você acessa (ex.: quais propriedades você vê nas respostas, quais parâmetros são obrigatórios nas requisições, etc.). E a versão em uso é definida pelo início do path da URL.

https://api.mailtop.com.br/v1/campanhas

No exemplo acima, a versão da API em uso é a v1.

Quando lançamos alterações que são compatíveis com a versão atual, nós apenas alteramos / adicionamos essas alterações, sem mudar o número da versão da API. Essas alterações aparecem na documentação, e também no Changelog desta página.

Porém, quando nós lançamos alterações que não são compatíveis com a versão atual, nós lançamos uma nova versão da API, com um novo path. Mas você não precisa alterar seu sistema para usar a nova versão imediatamente; a versão antiga ainda fica disponível por algum tempo, depois do lançamento de uma nova versão.

O que são alterações compatíveis com a versão atual?

O Mailtop considera como uma alteração compatível a:

  • Adição de novos métodos
  • Adição de novos parâmetros opcionais em requisições de métodos existentes
  • Adição de novas propriedades em respostas de métodos existentes
  • Alteração na ordem das propriedades em respostas de métodos existentes
  • Alteração do comprimento ou do formato de IDs e/ou chaves

Como utilizar a nova versão da API?

Se você está usando uma versão antiga da API, migrar para uma nova versão permitirá tirar vantagem de novas funcionalidades e desempenho melhorado. Para atualizar, basta alterar o path da URL para a versão desejada. Mas lembre-se: existem alterações entre uma versão e outra que podem fazer com que seu sistema deixe de funcionar.

Atualizar sua versão da API implica utilizar em seu sistema uma versão que:

  • tem novos métodos / endpoints
  • teve métodos / endpoints depreciados e/ou removidos
  • tem parâmetros obrigatórios e estrutura da resposta diferentes

Você deve consultar a documentação e testar a nova versão da API antes de colocar esta alteração em vigor em seu sistema. Assim que você tiver certeza que o seu código pode ser usado com a nova versão, faça a migração.

Por quanto tempo uma versão antiga da API fica disponível?

A partir do momento em que uma nova versão da API é lançada, a versão anterior seguirá o seguinte Cronograma de Depreciação:

Dias após novo lançamento Alterações feitas na API
Do 1.º ao 90.º dia Apenas alterações de desempenho e segurança são publicadas.
Do 91.º ao 180.º dia Apenas alterações de segurança são publicadas.
Após 180.º dia Todos os endpoints são desabilitados, e retornam código HTTP 410 (Gone).

Changelog

Esta lista mostra todas as atualizações feitas na estrutura da API, e não apenas as compatíveis com versões anteriores.

Setembro de 2019

  • Adiciona parâmetro opcional mostrar_logo em POST /campanhas e PATCH /campanhas/{campanha_id}

Julho de 2019

  • Adição de endpoints para envio de e-mails transacionais, em /transacionais

Abril de 2019

  • Adição do número de e-mails abertos e clicados, em GET /campanhas/{campanha_id}/dashboard

Fevereiro de 2018

  • Adição de download do arquivo da Exportação GET /exportacoes/{id}/download
  • Adição de consulta a lista de Exportações em GET /exportacoes
  • Adição de consulta a detalhes da Exportação em GET /exportacoes/{id}
  • Adição da geração do relatório Consolidado no fomato CSV em POST relatorios/csv_por_contato
  • Adição do resumo de relatório Consolidado em POST relatorios/consolidado

Janeiro de 2018

  • Adição de parâmetros querystring para filtrar Campanhas em GET /campanhas/

Novembro de 2017

  • Adição dos campos total_bounces e total_erros em GET /campanhas/{campanha_id}/dashboard

Outubro de 2017

  • Adição de parâmetros querystring para filtrar contatos em GET /listas/{lista_id}/contatos

Julho de 2017

  • Adição de consulta de saldo de créditos, em GET /creditos
  • Adição de consulta a lista de Faturas, em GET /faturas
  • Adição da pré-visualização do Segmento, em GET /listas/{lista_id}/segmento/preview

Junho de 2017

  • Adição do campo opcional segmento_id, em POST /campanhas e PUT /campanhas/{id}
  • Adição de endpoint para listagem de preços de pacotes individuais e planos mensais, em GET /ofertas
  • Adição de status do processo de Segmentação, em GET /listas/{lista_id}/segmento/id/status
  • Adição de teste de template por e-mail, em POST /campanhas/{campanha_id}/teste

01 de Junho de 2017

  • Lançamento da v1 da API.

Suporte

A documentação contém informações sobre os possíveis erros que podem acontecer em cada um dos endpoints. Porém, se estiver encontrando muitos erros HTTP 500, ou se tiver algum problema em acessar o nosso servidor, verifique o status de nossos serviços, ou entre em contato pelo e-mail suporte@mailtop.com.br.