Crie e gerencie sua chave de API

Publicado em: 16 de julho de 2026 · Última atualização: 12 de setembro de 2026 · Por Marcus Biel

A página “API key” (chave de API) permite que um sistema externo acesse, com autenticação, os endpoints da API do Maildroppa disponíveis para sua conta.

Você pode criar uma única chave de API, copiar seu valor secreto completo, redefini-la com segurança por meio da rotação ou excluí-la quando não for mais necessária. A mesma chave da conta pode ser usada por integrações executadas no servidor e por gatilhos de solicitação de API nas automações do Maildroppa.

Uma chave de API representa sua conta do Maildroppa. Trate-a como uma senha: qualquer pessoa que obtiver a chave poderá chamar os endpoints da API disponíveis para ela até que você faça a rotação ou a exclua.

Para que serve a chave de API

Use a chave de API quando um software externo precisar se comunicar com o Maildroppa sem que um usuário faça login de forma interativa.

Exemplos comuns incluem:

• Sincronizar assinantes com um CRM, loja, sistema de gestão de membros ou banco de dados interno.
• Criar ou atualizar assinantes a partir de uma aplicação executada no servidor.
• Consultar ou gerenciar tags, campos, valores de campos e segmentos por meio dos endpoints disponíveis.
• Enviar eventos personalizados para um gatilho de solicitação de API em uma automação.
• Enviar mensagens de e-mail transacionais pela API.
• Gerenciar assinaturas de webhooks baseadas em API.

A chave de API se destina à comunicação entre servidores. Ela não deve ser usada em código executado no navegador de um visitante, em um site público, em um aplicativo móvel ou em um formulário de inscrição incorporado.

A página está atualmente marcada como “beta”. Use a documentação OpenAPI vinculada como referência para os endpoints, corpos de solicitação, parâmetros e esquemas de resposta compatíveis com a versão atual da API.

Como abrir a página da chave de API

Abra “Settings”, expanda “Developers” e selecione “API key”.

Você também pode abrir a página diretamente em:

https://app.maildroppa.com/settings/developers/api-key

A página contém:

• Um painel da chave de API com um selo beta.
• Um link “View OpenAPI docs”.
• Um estado vazio e o botão “Create API key” quando não há nenhuma chave.
• Uma representação mascarada da chave atual quando há uma.
• Um botão “Copy” que copia a chave completa.
• As ações “Rotate API key” e “Delete API key” para substituir ou remover a chave atual.

O Maildroppa permite uma chave de API por conta. A página não cria chaves separadas para cada aplicação, ambiente ou membro da equipe.

Como criar uma chave de API

Quando a página exibir “No API key yet”, clique em “Create API key”.

O Maildroppa cria a chave imediatamente. Não há uma caixa de diálogo de confirmação nessa primeira criação. Enquanto a solicitação está em andamento, o botão muda para “Creating API key” e a página desativa temporariamente as demais ações relacionadas à chave.

Depois que a chave for criada:

• O estado vazio desaparece.
• Uma chave mascarada é exibida.
• As ações “Copy”, “Rotate API key” e “Delete API key” ficam disponíveis.
• O Maildroppa exibe a mensagem de sucesso “API key updated”.

Se já houver outra chave para a conta, o Maildroppa não criará uma segunda. Use a chave existente ou faça a rotação dela.

Entenda a chave mascarada

A página não exibe o segredo completo em texto aberto. Ela mostra os cinco primeiros caracteres seguidos de cinco asteriscos, por exemplo:

a1b2c*****

Isso é apenas uma máscara visual. Os asteriscos não representam o tamanho real da chave, e o valor mascarado não pode ser usado em uma solicitação de API.

Clique em “Copy” para copiar a chave atual completa para a área de transferência. Após uma cópia bem-sucedida, o botão muda brevemente para “Copied!”.

A chave continua mascarada quando você retorna à página, mas “Copy” continua copiando o valor atual completo. Portanto, não é necessário fazer a rotação de uma chave válida só porque você não a salvou durante a criação.

Como armazenar a chave com segurança

Transfira a chave copiada diretamente para o armazenamento de segredos usado pela integração.

Locais adequados incluem:

• Um gerenciador de segredos gerenciado.
• A configuração protegida do ambiente do servidor.
• Um segredo de implantação criptografado.
• Um gerenciador de senhas usado para recuperação operacional.

Não armazene a chave em:

• JavaScript executado no navegador ou outro pacote de frontend que possa ser baixado.
• Um arquivo de código-fonte público ou privado incluído em um commit de repositório.
• Uma URL ou um parâmetro de consulta.
• Documentação pública, capturas de tela, mensagens de suporte ou sistemas de acompanhamento de problemas.
• Logs compartilhados da aplicação, eventos de análise ou relatórios de erros.
• Uma planilha não criptografada ou uma conversa comum da equipe.

Não adicione a chave a um exemplo de curl que será copiado para a documentação ou para um histórico do shell compartilhado com outras pessoas. Prefira uma variável de ambiente como MAILDROPPA_API_KEY.

Como usar a chave de API

Envie a chave completa no cabeçalho X-API-Key da solicitação HTTP:

X-API-Key: your-complete-api-key

Não a envie como um token Bearer. O Maildroppa espera X-API-Key, não Authorization: Bearer ....

A API de produção e sua documentação OpenAPI interativa estão disponíveis em:

https://api.maildroppa.com

Clique em “View OpenAPI docs” na página da chave de API para abrir a documentação em uma nova aba do navegador. Selecione um endpoint para consultar seu método, caminho, parâmetros, corpo da solicitação, tipo de resposta e possíveis códigos de status.

Exemplo de solicitação

O exemplo a seguir recupera a primeira página de assinantes. Ele lê a chave de uma variável de ambiente, em vez de colocar o segredo diretamente no comando:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Defina a variável no ambiente seguro em que a integração é executada. O método, o caminho, os parâmetros de consulta e o corpo exatos dependem do endpoint. Copie esses detalhes da documentação OpenAPI, em vez de tentar deduzi-los a partir das ações disponíveis na aplicação do Maildroppa.

Solicitações com corpo JSON

Para uma solicitação que envia JSON, inclua também:

Content-Type: application/json

Por exemplo, a estrutura básica é:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint e seu corpo são exemplos usados como marcadores de posição. Substitua-os por um endpoint documentado e seu respectivo esquema de solicitação documentado.

O que a chave pode acessar

A chave funciona apenas com endpoints compatíveis com autenticação por chave de API. Uma página ou solicitação usada internamente pela aplicação do Maildroppa não faz automaticamente parte da API pública para clientes.

A documentação OpenAPI apresenta a API oficialmente disponível para clientes. Se um caminho não estiver documentado para uso com chave de API, não presuma que a chave possa acessá-lo.

A página da chave de API não oferece escopos nem caixas de seleção de permissões por endpoint. Portanto, a chave atual da conta deve ser tratada como uma credencial de alto valor, mesmo que uma integração use apenas um endpoint.

Limites de requisições

O contrato OpenAPI atual documenta estes limites para chaves de API:

• API padrão para clientes: 300 solicitações por minuto e 2.000 solicitações por hora.
• API de eventos em /events: 100 solicitações por segundo, com capacidade de rajada de 500 solicitações.

Esses limites são aplicados à conta do Maildroppa, não de forma independente a cada script que compartilha a chave. Portanto, várias integrações podem consumir a mesma cota.

Quando o Maildroppa retornar 429 Too Many Requests, pare de enviar novas solicitações e respeite o cabeçalho de resposta Retry-After quando ele estiver presente. Use uma fila e intervalos controlados entre tentativas, em vez de iniciar muitas novas tentativas em paralelo.

As políticas de limites de requisições podem mudar enquanto a API estiver em beta. Consulte as informações no início da documentação OpenAPI antes de projetar integrações de alto volume.

Como usar a chave em solicitações de API de automações

Uma automação pode começar quando seu sistema envia um evento personalizado para a API de eventos do Maildroppa.

Ao configurar um gatilho “API request”, o Maildroppa usa a mesma chave de API da conta gerenciada nesta página. A configuração do gatilho pode criar a chave quando não houver nenhuma e copiar uma solicitação curl pronta, contendo a chave completa.

Isso tem duas consequências importantes:

• Fazer a rotação ou excluir a chave da conta também afeta os sistemas que enviam eventos personalizados para automações.
• Um exemplo de solicitação de automação copiado contém o segredo na área de transferência, mesmo que a chave esteja mascarada na tela.

Antes de fazer a rotação ou excluir a chave, inclua todos os gatilhos de solicitação de API e todos os sistemas externos que enviam eventos no inventário de integrações.

Como redefinir ou substituir a chave de API

Use “Rotate API key” quando precisar redefinir ou substituir a credencial atual. O Maildroppa cria uma nova chave e invalida a anterior como parte da mesma ação.

Faça a rotação quando:

• Houver a possibilidade de a chave ter sido exposta.
• Uma pessoa ou um provedor que conhecia a chave não precisar mais de acesso.
• Sua política de segurança exigir a substituição periódica de credenciais.
• Você quiser substituir uma chave armazenada em um local antigo ou inseguro.

Clique em “Rotate API key” abaixo da chave mascarada. O Maildroppa abre uma caixa de diálogo de aviso explicando que a chave existente não poderá mais ser usada.

Clique em “Rotate API key” na caixa de diálogo para continuar ou em “Cancel” para manter a chave atual.

A rotação não tem período de carência

Após a confirmação da rotação, a chave antiga deixa de funcionar imediatamente. O Maildroppa não mantém as chaves antiga e nova válidas ao mesmo tempo.

Como a conta tem apenas uma chave, a rotação afeta todos os servidores, tarefas agendadas, integrações, scripts e sistemas de envio de eventos para automações que a utilizam.

Siga esta sequência para uma rotação planejada:

1. Liste todas as integrações que usam a chave atual.
2. Prepare o acesso à configuração de segredos e ao processo de implantação de cada integração.
3. Escolha uma breve janela de manutenção se o acesso ininterrupto à API for importante.
4. Clique em “Rotate API key” e confirme o aviso clicando em “Rotate API key” na caixa de diálogo.
5. Clique em “Copy” para copiar a nova chave completa.
6. Substitua imediatamente o segredo em todas as integrações.
7. Reinicie ou reimplante os serviços que carregam segredos apenas durante a inicialização.
8. Envie uma solicitação documentada e inofensiva para verificar cada integração.
9. Verifique se há respostas 401 Unauthorized de algum serviço esquecido que ainda esteja usando a chave antiga.

Se houver suspeita de comprometimento da chave atual, faça a rotação imediatamente e aceite a breve interrupção necessária para atualizar os sistemas legítimos.

Como excluir a chave de API

Exclua a chave quando a conta não precisar mais aceitar solicitações autenticadas por chave de API.

Clique em “Delete API key” abaixo da chave mascarada. O Maildroppa abre uma caixa de diálogo de aviso explicando que a chave será removida permanentemente da conta.

Clique em “Delete API key” na caixa de diálogo para excluí-la ou em “Cancel” para mantê-la.

Após a exclusão:

• A chave atual deixa de funcionar imediatamente.
• A página retorna ao estado “No API key yet”.
• As integrações de servidor que usam a chave excluída não conseguem mais se autenticar.
• Os sistemas que enviam solicitações de API para automações usando essa chave não conseguem mais entregar eventos.

Excluir uma chave não exclui assinantes, campanhas, tags, campos, segmentos, automações nem outros dados da conta. A ação remove a credencial usada para acessar os endpoints compatíveis da API.

Você pode clicar em “Create API key” posteriormente para criar uma nova credencial. O valor excluído não é restaurado. Todas as integrações precisam ser atualizadas antes de poderem usar a nova chave.

Redefinir ou excluir: qual opção escolher?

Escolha “Rotate API key” quando o acesso à API precisar continuar com uma nova credencial.

Escolha a exclusão quando o acesso à API precisar ser interrompido completamente, pelo menos por enquanto.

Ambas as ações invalidam a chave atual imediatamente. A rotação cria a substituta como parte da mesma ação; a exclusão deixa a conta sem uma chave.

Recomendações de segurança

Mantenha as chamadas de API no servidor

Um navegador ou aplicativo móvel não consegue manter um segredo incorporado de forma confiável. Um usuário pode inspecionar a aplicação, os cabeçalhos das solicitações, os mapas de código-fonte ou o tráfego de rede e extrair a chave.

Se um site ou aplicativo precisar acionar uma ação, envie primeiro a solicitação ao seu próprio backend autenticado. Deixe que esse backend valide o usuário e chame o Maildroppa usando a chave armazenada no servidor.

Reduza a exposição ao mínimo possível

Forneça a chave apenas aos sistemas que precisam dela. Não a distribua a todos os desenvolvedores nem a cole em vários arquivos de configuração locais.

Como a página atualmente gerencia uma única chave para toda a conta, em vez de várias chaves nomeadas ou com escopos, use um serviço interno de integração ou um proxy se várias aplicações precisarem de maior isolamento entre si.

Oculte dados sensíveis nos cabeçalhos das solicitações

Configure clientes HTTP, proxies reversos, ferramentas de observabilidade e sistemas de relatório de erros para ocultar X-API-Key. Uma solicitação pode funcionar corretamente e, ainda assim, expor a credencial nos logs de depuração.

Mantenha os ambientes separados

Não reutilize uma chave de produção em desenvolvimento local, código de exemplo, capturas de tela ou dados de teste. Armazene os segredos de cada ambiente em um armazenamento de segredos específico para esse ambiente.

O link “View OpenAPI docs” direciona automaticamente os usuários do ambiente de produção para a documentação da API de produção. Sempre verifique o nome do host antes de enviar uma chave real.

Faça a rotação após qualquer suspeita de exposição

Excluir uma mensagem, um commit de repositório, uma linha de log ou uma captura de tela não prova que ninguém copiou a chave. Se o valor completo foi exposto, faça a rotação.

Como tratar erros de API

Use o status HTTP e o corpo de resposta documentado para decidir o que a integração deve fazer.

Os casos comuns incluem:

• 400 Bad Request — O caminho, o parâmetro ou o corpo JSON não atende ao contrato do endpoint. Compare a solicitação com o esquema OpenAPI.
• 401 Unauthorized — O cabeçalho X-API-Key está ausente, vazio, contém uma chave inválida ou excluída, ou ainda usa um valor antigo após uma rotação.
• 403 Forbidden — A chave autenticada não tem permissão para usar essa operação.
• 404 Not Found — O caminho ou recurso referenciado não existe nesta conta.
• 429 Too Many Requests — A integração atingiu um limite de requisições da API. Pause as solicitações e respeite o cabeçalho Retry-After quando ele estiver presente.
• 5xx — O Maildroppa não conseguiu concluir a solicitação. Repita as operações seguras com intervalos exponencialmente maiores entre tentativas, respeitando um limite, e registre logs que não incluam a chave de API.

Não repita indiscriminadamente todas as solicitações que falharem. Corrija os problemas que geram respostas 400, 401, 403 e a maioria das respostas 404 antes de enviar a mesma solicitação novamente.

Para solicitações que alteram dados, confirme o comportamento do endpoint em relação a novas tentativas e à idempotência antes de repetir uma solicitação automaticamente. Uma falha de conexão nem sempre prova que o Maildroppa não fez nenhuma alteração.

Solução de problemas

“Create API key” continua visível

No momento, não há nenhuma chave na conta. Clique no botão uma vez e aguarde a conclusão da solicitação.

Se a criação falhar, recarregue a página antes de tentar novamente. Outra página ou configuração de automação pode já ter criado a chave da conta.

A chave na página parece curta demais

A página mostra intencionalmente apenas os cinco primeiros caracteres e *****. Clique em “Copy” para copiar o valor completo. Não envie o texto mascarado em uma solicitação.

“Copy” não muda para “Copied!”

O navegador pode ter bloqueado o acesso à área de transferência. Mantenha a página na aba ativa, permita o acesso à área de transferência se solicitado e clique em “Copy” novamente.

Não tente reconstruir a chave a partir do texto mascarado.

Uma solicitação retorna 401 Unauthorized

Verifique se:

• O nome do cabeçalho é exatamente X-API-Key.
• O cabeçalho contém o valor completo, sem os asteriscos visíveis.
• A integração não está enviando Authorization: Bearer no lugar do cabeçalho correto.
• Nenhum espaço em branco, aspas ou quebra de linha foi adicionado ao segredo.
• Ninguém fez a rotação ou excluiu a chave da conta.
• O serviço foi reiniciado, caso leia variáveis de ambiente apenas na inicialização.
• A solicitação é enviada ao ambiente correto da API do Maildroppa.

Uma integração funciona, mas outra parou após a rotação

A segunda integração provavelmente ainda está usando a chave antiga. Não há período de sobreposição. Atualize o segredo e reinicie qualquer processo que armazene a configuração em cache.

A página OpenAPI funciona, mas um endpoint retorna 403

Nem todo endpoint da aplicação é compatível com autenticação por chave de API. Use uma operação documentada para a API de clientes e confirme seus requisitos de autenticação na página OpenAPI.

As solicitações retornam 429 Too Many Requests

Reduza as rajadas de solicitações, coloque o trabalho em fila e tente novamente após o intervalo informado pela API. Evite um volume excessivo de novas tentativas em paralelo. Se várias aplicações compartilharem a única chave da conta, coordene o volume de solicitações, pois elas compartilham os limites de API da conta.

Lista de verificação da configuração recomendada

Antes de colocar uma integração em uso regular, confirme que:

• A chave está armazenada apenas na configuração de segredos do servidor.
• As solicitações usam o cabeçalho X-API-Key.
• A integração usa https://api.maildroppa.com em produção.
• Cada método, caminho, parâmetro e corpo JSON segue a documentação OpenAPI.
• Os logs e relatórios de erros ocultam a chave.
• Os tempos limite e os limites para novas tentativas estão configurados.
• Erros 401, 403, 429 e erros de servidor são monitorados.
• O responsável pela integração está registrado.
• Todos os sistemas que compartilham a chave da conta estão incluídos no plano de rotação.
• É possível fazer rapidamente a rotação de uma chave comprometida.

A página da chave de API é simples de propósito, mas suas ações afetam todas as integrações de API conectadas à conta. Crie a chave somente quando necessário, mantenha-a em servidores confiáveis e planeje a rotação como uma mudança de credencial que afeta toda a conta.