Crie e gerencie sua chave de API

Published: 16 de julho de 2026 · Last updated: 21 de julho de 2026 · By Marcus Biel

A página Chave de API fornece a um sistema externo acesso autenticado aos endpoints compatíveis da API do Maildroppa em sua conta.

Você pode criar uma chave de API, copiar seu valor secreto completo, redefini-la com segurança fazendo uma rotação ou excluí-la quando não for mais necessária. A mesma chave da conta pode ser usada por integrações do lado do servidor e por gatilhos de solicitações 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 uma rotação ou a exclua.

Para que serve a chave de API

Use a chave de API quando um software externo ao Maildroppa precisar trabalhar com o Maildroppa sem um login interativo de usuário.

Exemplos comuns incluem:

• Sincronizar assinantes com um CRM, loja, sistema de associação ou banco de dados interno.
• Criar ou atualizar assinantes a partir de uma aplicação do lado do servidor.
• Ler ou gerenciar tags, campos, valores de campos e segmentos por meio de endpoints compatíveis.
• Enviar eventos personalizados para um gatilho de solicitação de API em uma Automação.
• Enviar Mensagens de e-mail transacionais por meio da API.
• Gerenciar assinaturas de webhooks baseadas em API.

A chave de API destina-se à comunicação entre servidores. Ela não se destina a códigos executados no navegador de um visitante, em um site público, em uma aplicação 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 fonte para consultar os endpoints, corpos de solicitação, parâmetros e esquemas de resposta compatíveis atualmente com a API.

Abrindo a página Chave de API

Abra “Configurações”, expanda “Desenvolvedores” e selecione “Chave de API”.

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 “Ver documentos OpenAPI”.
• Um estado vazio e o botão “Criar chave de API” quando não existe nenhuma chave.
• Uma representação mascarada da chave atual quando existe uma.
• Um botão “Copiar” que copia a chave completa.
• Ações “Fazer rotação da chave de API” e “Excluir chave de API” 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 aplicações, ambientes ou membros da equipe individuais.

Criando uma chave de API

Quando a página exibir “Ainda não há uma chave de API”, clique em “Criar chave de API”.

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

Depois que a chave for criada:

• O estado vazio desaparece.
• Uma chave mascarada é exibida.
• As ações “Copiar”, “Fazer rotação da chave de API” e “Excluir chave de API” ficam disponíveis.
• O Maildroppa exibe uma mensagem de sucesso “Chave de API atualizada”.

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

Entendendo a chave mascarada

A página não exibe o segredo completo como texto comum. 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 comprimento real da chave, e o valor mascarado não pode ser usado em uma solicitação de API.

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

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

Armazenando 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 administrado.
• 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 baixável.
• Um arquivo de código-fonte público ou privado enviado para um repositório.
• Uma URL ou 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 conversa comum da equipe.

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

Usando a chave de API

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

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 “Ver documentos OpenAPI” na página 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, caminho, parâmetros de consulta e 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 Maildroppa.

Solicitações com corpos 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 placeholders. Substitua-os por um endpoint documentado e seu 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 Maildroppa não faz automaticamente parte da API pública para clientes.

A documentação OpenAPI mostra a API de clientes compatível. 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 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 único endpoint.

Limites de taxa

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 independentemente 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 um recuo controlado em vez de iniciar muitas novas tentativas em paralelo.

As políticas de limite de taxa podem evoluir 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.

Usando a chave para solicitações de API de Automação

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

Quando você configura um gatilho de “solicitação de API”, o Maildroppa usa a mesma chave de API da conta gerenciada nesta página. A configuração do gatilho pode criar a chave quando nenhuma existir e pode copiar uma solicitação curl preparada contendo a chave completa.

Isso tem duas consequências importantes:

• Fazer uma 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, embora a chave esteja mascarada na tela.

Antes de fazer uma rotação ou excluir a chave, inclua todos os gatilhos de solicitação de API e todos os remetentes externos de eventos no inventário da sua integração.

Redefinindo ou substituindo a chave de API

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

Use a rotação quando:

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

Clique em “Fazer rotação da chave de API” 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 “Fazer rotação da chave de API” na caixa de diálogo para continuar ou clique em “Cancelar” para manter a chave atual.

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

Depois que você confirmar a rotação, a chave antiga deixará 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 remetentes de eventos de Automação que a utilizam.

Use 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 “Fazer rotação da chave de API” e confirme o aviso clicando em “Fazer rotação da chave de API” na caixa de diálogo.
5. Clique em “Copiar” 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. Procure respostas 401 Unauthorized de um serviço esquecido que ainda esteja usando a chave antiga.

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

Excluindo a chave de API

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

Clique em “Excluir chave de API” 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 “Excluir chave de API” na caixa de diálogo para excluí-la ou clique em “Cancelar” para mantê-la.

Após a exclusão:

• A chave atual deixa de funcionar imediatamente.
• A página retorna ao estado “Ainda não há uma chave de API”.
• As integrações de servidor que usam a chave excluída não podem mais se autenticar.
• Os remetentes de solicitações de API de Automação que usam essa chave não podem mais entregar eventos.

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

Você pode clicar em “Criar chave de API” 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 “Fazer rotação da chave de API” quando o acesso à API deverá continuar com uma nova credencial.

Escolha a exclusão quando o acesso à API deverá 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 seu servidor

Um navegador ou aplicativo móvel não consegue manter com segurança um segredo incorporado. Um usuário pode inspecionar a aplicação, os cabeçalhos das solicitações, os mapas de origem 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. Permita 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 proxy se várias aplicações precisarem de um isolamento mais forte entre si.

Redija os 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 vazar sua credencial por meio de logs de depuração.

Mantenha 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 segredos específicos de cada ambiente em armazenamentos de segredos específicos do ambiente.

O link “Ver documentos OpenAPI” direciona automaticamente os usuários de produção para a documentação da API de produção. Sempre verifique o hostname antes de enviar uma chave real.

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

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

Tratando 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, parâmetro ou 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, inválido, excluído ou contém 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 taxa 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. Tente novamente operações seguras com recuo exponencial limitado e registre logs que não incluam a chave de API.

Não repita todas as falhas cegamente. Corrija as 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 de novas tentativas e de idempotência do endpoint 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

“Criar chave de API” continua visível

Atualmente não existe 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 “Copiar” para copiar o valor completo. Não envie o texto mascarado em uma solicitação.

“Copiar” não muda para “Copiado!”

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 “Copiar” 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 em vez disso.
• Nenhum espaço em branco, aspas ou nova linha foi adicionado ao segredo.
• Ninguém fez uma rotação ou excluiu a chave da conta.
• Um serviço foi reiniciado se ele lê 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 atraso retornado pela API. Evite tempestades 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 lado 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.
• Estão configurados tempos limite e novas tentativas limitadas.
• Erros 401, 403, 429 e erros do 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.
• Uma chave comprometida pode ser substituída rapidamente.

A página Chave de API é deliberadamente pequena, 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 alteração de credencial para toda a conta.