Ir para o conteúdo principal

Chaves API

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, editá-las e excluir as que não precisa mais.

Seção Chaves API da Mailrelay com o botão +Adicionar e a lista de chaves

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 página Nova chave API será aberta. Em Nome, escreva um nome que ajude você a identificar a chave, por exemplo "CRM" ou "Integração do site". Este campo é obrigatório.
  3. No menu suspenso Usuário, escolha o usuário da conta ao qual a chave será atribuída.
  4. Em Expiração, escolha quando a chave deixará de funcionar: 7 dias, 14 dias, 1 mês, 3 meses, 6 meses, 1 ano, Sem expiração ou Personalizada. Abaixo do campo você verá a data em que ela expira. Se escolher Personalizada, aparece um campo para escolher a data e a hora em que a chave deixará de funcionar.
  5. Em Endereços IP permitidos, você pode indicar de quais endereços a chave poderá ser usada: um endereço IPv4 ou IPv6, ou um intervalo CIDR. Com +Adicionar mais é adicionado outro campo para mais um endereço, e com Adicionar meu IP ele é preenchido com o endereço IP do qual você está conectado. Se deixar o campo vazio, são permitidas solicitações de qualquer IP.

Página Nova chave API com os campos Nome, Usuário, Expiração, Endereços IP permitidos e Permissões

  1. Em Permissões, escolha o que a chave pode fazer:
    • Acesso total: tudo o que o seu usuário pode fazer, incluindo áreas adicionadas à API no futuro.
    • Restrito (recomendado): você escolhe o acesso para cada área: Contatos, Campanhas de email, Email transacional, SMS, SMS transacional, WhatsApp, WhatsApp transacional, Ecommerce, Biblioteca de mídia e Webhooks. Todas as áreas começam sem acesso. Abaixo de cada área é indicado o que ela inclui, e no seu menu suspenso você escolhe o nível, por exemplo Ler ou Ler e escrever.
    Por exemplo, se uma integração só precisa adicionar assinantes às listas da sua newsletter ou das suas campanhas de e-mail marketing, você pode dar a ela acesso apenas a Contatos.

Permissões no modo Restrito com o menu suspenso de acesso de cada área

  1. Clique em Criar Chave API.
  2. 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.

Janela Chave de API criada com o aviso de que a chave só será exibida uma vez e o botão para copiá-la

  1. Clique em Fechar.

A nova chave aparecerá na lista. Para cada chave, você verá o nome, o usuário ao qual ela está atribuída, os primeiros caracteres da chave (para que você possa identificá-la), o status, a data e a hora de expiração, os endereços IP permitidos 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. Além disso, a chave só pode fazer o que suas permissões e seu usuário permitirem: mesmo que você escolha Acesso total, ela nunca poderá fazer mais do que o perfil desse usuário permite.

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. Para ver como são definidas as permissões de cada usuário, consulte Perfis.

Como editar uma chave API

Na lista de Configurações > Chaves API, clique no botão verde de edição que aparece à direita da chave. A página Editar chave API será aberta, com os mesmos campos de quando ela foi criada: Nome, Usuário, Expiração, Endereços IP permitidos e Permissões. Em Expiração aparece também a opção Manter a expiração atual. Quando terminar, clique em Atualizar Chave API para salvar as alterações.

Página Editar chave API com a opção Manter a expiração atual e o botão Atualizar Chave API

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. O painel pedirá que você confirme que deseja excluí-la. A partir desse momento, qualquer sistema que continue usando essa chave perderá o acesso à sua conta.

Como verificar se a chave funciona

Na documentação da API, seção "First request", é explicado como fazer uma primeira requisição para verificar se a sua chave é válida.

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.

Assim, você pode, por exemplo, conectar seu site ou sua loja virtual para que os novos contatos sejam adicionados automaticamente à lista da sua newsletter, sem precisar importá-los manualmente antes de cada envio de e-mails em massa.

O envio de emails transacionais através da API requer o pacote SMTP + API. Todos os outros endpoints da API continuam disponíveis.

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

Limites de uso da API

A API tem limites de requisições. Os valores vigentes estão na documentação da API, seção "Rate limiting".

Boas práticas de segurança

Uma chave API dá acesso à 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.
  • Se uma integração não precisa de todas as áreas, escolha Restrito em Permissões, que é a opção recomendada pelo painel, e dê acesso apenas ao que ela usa.
  • 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. Para enviar e-mails transacionais através da API, você precisa do pacote SMTP + API.

Posso ter várias chaves API?

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

Posso limitar o que uma chave API faz?

Sim. Ao criar ou editar a chave, em Permissões escolha Restrito e dê a cada área apenas o acesso de que ela precisa. Você também pode indicar em Endereços IP permitidos de quais endereços ela poderá ser usada.

Posso mudar a expiração de uma chave que já criei?

Sim. Na página Editar chave API, escolha uma nova opção em Expiração, ou deixe Manter a expiração atual se não quiser alterá-la.

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.

Este artigo foi útil?

Que bom!

Obrigado pelo seu feedback

Desculpe! Não conseguimos ajudar você

Obrigado pelo seu feedback

Deixe-nos saber como podemos melhorar este artigo!

Selecione pelo menos um dos motivos
A verificação do CAPTCHA é obrigatória.

Feedback enviado

Agradecemos seu esforço e tentaremos corrigir o artigo