Chaves API: como criar e gerenciar

Uma chave API é um código único que permite que outro aplicativo (seu site, seu CRM, sua loja virtual ou um desenvolvimento próprio) se conecte à sua conta da Mailrelay sem usar seu usuário e senha. Com ela, esses sistemas podem adicionar assinantes, enviar e-mails transacionais ou consultar estatísticas de forma automática.

Você vai precisar de uma chave API se for integrar a Mailrelay a outra ferramenta, se usar um plugin ou conector que a solicite, ou se sua equipe de desenvolvimento for trabalhar com a API da Mailrelay. As chaves API estão disponíveis em todas as contas, inclusive na conta gratuita.

Onde encontrar as chaves API

Na sua conta da Mailrelay, acesse Configurações > Chaves API. Nessa seção você pode ver as chaves que já existem, criar novas e excluir as que não precisa mais.

Na parte superior da página você também encontrará um link para a documentação da API, que inclui exemplos de código para facilitar o trabalho da equipe de desenvolvimento.

Como criar uma chave API passo a passo

1. Em Configurações > Chaves API, clique em +Adicionar.
2. A janela Nova chave API será aberta. No menu suspenso Usuário, escolha o usuário da conta ao qual a chave será atribuída.
3. Clique em Criar Chave API.

4. A janela Chave de API criada será aberta com a sua nova chave. Copie-a com o botão que aparece ao lado dela e guarde-a em um local seguro. Por segurança, a chave completa só é exibida desta vez: depois de fechar a janela, você não poderá vê-la novamente.

5. Clique em Fechar.

A nova chave aparecerá na lista. Para cada chave, você verá o usuário ao qual ela está atribuída, os primeiros caracteres da chave (para que você possa identificá-la), a data de criação e a data do último uso.

Por que cada chave é atribuída a um usuário

Todas as ações realizadas com uma chave API ficam registradas em nome do usuário ao qual ela está atribuída. Por isso, é recomendável criar um usuário específico para cada integração (por exemplo, "Integração do site" ou "CRM"). Assim você saberá qual sistema fez cada alteração e poderá gerenciar cada integração separadamente.

Se precisar criar esse usuário, consulte Como adicionar um usuário à conta e Usuários.

Como excluir uma chave API

Se uma integração não é mais usada ou se você acha que uma chave foi comprometida, exclua-a na lista de Configurações > Chaves API com o botão vermelho de lixeira que aparece à direita de cada chave. A partir desse momento, qualquer sistema que continue usando essa chave perderá o acesso à sua conta.

A coluna de último uso ajuda você a identificar chaves que não são mais usadas e que podem ser excluídas com segurança.

Como verificar se a chave funciona

Para verificar se a chave é válida, você pode fazer uma requisição de teste ao endpoint /ping. A chave é enviada no cabeçalho X-AUTH-TOKEN. Se estiver tudo certo, a API responderá com o código HTTP 204.

curl -X GET --header 'X-AUTH-TOKEN: SUA-CHAVE-API' 'https://SUA-CONTA.ipzmarketing.com/api/v1/ping'

Substitua SUA-CHAVE-API pela chave que você criou e SUA-CONTA.ipzmarketing.com pelo domínio da sua conta da Mailrelay, que é o que aparece na barra de endereços do navegador quando você acessa o seu painel.

O que você pode fazer com a API da Mailrelay

Com uma chave API você pode automatizar, entre outras coisas:

• Adicionar, atualizar ou descadastrar assinantes, e gerenciar seus grupos e etiquetas.
• Enviar e-mails transacionais, SMS e mensagens de WhatsApp.
• Criar e enviar campanhas, e consultar suas estatísticas: aberturas, cliques e descadastros.
• Gerenciar remetentes, campos personalizados e importações.
• Receber avisos automáticos quando determinados eventos acontecem na sua conta.

Você encontrará todos os endpoints disponíveis, com seus parâmetros e exemplos, na documentação da API. Estes artigos também podem interessar a você:

• SMS usando nossa API
• Subscrição de eventos
• O que são e-mails transacionais? Opções SMTP e API

Limites de uso da API

A API tem limites de requisições. Os valores vigentes, o erro 429 retornado ao ultrapassá-los e os cabeçalhos que indicam quantas requisições restam estão na documentação da API, seção "Rate limiting"

Boas práticas de segurança

Uma chave API dá acesso total à sua conta, por isso é importante protegê-la como se fosse uma senha:

• Não a compartilhe por e-mail nem a inclua no código público do seu site.
• Use uma chave diferente para cada integração, atribuída ao seu próprio usuário.
• Guarde as chaves em um gerenciador de senhas ou na configuração segura do seu servidor.
• Se você acha que uma chave foi comprometida, crie uma nova, atualize suas integrações e exclua a anterior.
• Revise a lista de vez em quando e exclua as chaves que você não usa mais.

Perguntas frequentes

Perdi minha chave API. Posso recuperá-la?

Não. Por segurança, a chave completa só é exibida no momento em que é criada. Crie uma nova chave, atualize com ela as integrações que usavam a anterior e exclua a chave antiga da lista.

Posso usar a API com a conta gratuita?

Sim. A seção Chaves API também está disponível na conta gratuita.

Posso ter várias chaves API?

Sim. Você pode criar várias chaves e atribuir cada uma a um usuário diferente da conta.

Onde encontro o domínio da minha conta?

É o domínio que aparece na barra de endereços do navegador quando você acessa o seu painel da Mailrelay, por exemplo suaempresa.ipzmarketing.com.