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.

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
- Em Configurações > Chaves API, clique em +Adicionar.
- 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.
- No menu suspenso Usuário, escolha o usuário da conta ao qual a chave será atribuída.
- 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.
- 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.

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

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

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

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.