Crea y administra tu clave de API

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

La página Clave de API proporciona a un sistema externo acceso autenticado a los endpoints de la API de Maildroppa compatibles con tu cuenta.

Puedes crear una clave de API, copiar su valor secreto completo, restablecerla de forma segura rotándola o eliminarla cuando ya no la necesites. La misma clave de cuenta puede utilizarse para integraciones del lado del servidor y para activadores de solicitudes de API en Maildroppa Automations.

Una clave de API representa tu cuenta de Maildroppa. Trátala como una contraseña: cualquiera que obtenga la clave podrá llamar a los endpoints de API disponibles para esa clave hasta que la rotes o la elimines.

Para qué sirve la clave de API

Usa la clave de API cuando un software externo a Maildroppa necesite trabajar con Maildroppa sin un inicio de sesión de usuario interactivo.

Algunos ejemplos habituales son:

• Sincronizar suscriptores con un CRM, una tienda, un sistema de membresías o una base de datos interna.
• Crear o actualizar suscriptores desde una aplicación del lado del servidor.
• Leer o administrar etiquetas, campos, valores de campos y segmentos mediante los endpoints compatibles.
• Enviar eventos personalizados a un activador de solicitudes de API en una Automation.
• Enviar mensajes de correo electrónico transaccionales mediante la API.
• Administrar suscripciones a webhooks basadas en API.

La clave de API está pensada para la comunicación de servidor a servidor. No está destinada al código que se ejecuta en el navegador de un visitante, un sitio web público, una aplicación móvil o un formulario de registro integrado.

La página está marcada actualmente como “beta”. Usa la documentación de OpenAPI vinculada como fuente de los endpoints, cuerpos de solicitud, parámetros y esquemas de respuesta compatibles actualmente con la API.

Abrir la página Clave de API

Abre “Settings”, expande “Developers” y selecciona “API key”.

También puedes abrir la página directamente en:

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

La página contiene:

• Un panel de clave de API con una insignia beta.
• Un enlace “View OpenAPI docs”.
• Un estado vacío y un botón “Create API key” cuando no existe ninguna clave.
• Una representación enmascarada de la clave actual cuando existe.
• Un botón “Copy” que copia la clave completa.
• Acciones “Rotate API key” y “Delete API key” para reemplazar o eliminar la clave actual.

Maildroppa permite una clave de API por cuenta. La página no crea claves independientes para aplicaciones, entornos o miembros del equipo.

Crear una clave de API

Cuando la página muestre “No API key yet”, haz clic en “Create API key”.

Maildroppa crea la clave inmediatamente. No aparece ningún diálogo de confirmación para esta primera creación. Mientras se procesa la solicitud, el botón cambia a “Creating API key” y la página desactiva temporalmente las demás acciones relacionadas con la clave.

Después de crear la clave:

• Desaparece el estado vacío.
• Aparece una clave enmascarada.
• Las acciones “Copy”, “Rotate API key” y “Delete API key” están disponibles.
• Maildroppa muestra un mensaje de éxito “API key updated”.

Si ya existe otra clave para la cuenta, Maildroppa no crea una segunda. Usa la clave existente o rótala.

Entender la clave enmascarada

La página no muestra el secreto completo como texto normal. Muestra los primeros cinco caracteres seguidos de cinco asteriscos, por ejemplo:

a1b2c*****

Esto es solo una máscara visual. Los asteriscos no representan la longitud real de la clave y el valor enmascarado no puede utilizarse en una solicitud de API.

Haz clic en “Copy” para copiar la clave actual completa al portapapeles. Después de copiarla correctamente, el botón cambia brevemente a “Copied!”.

La clave permanece enmascarada cuando vuelves a la página, pero “Copy” sigue copiando el valor actual completo. Por lo tanto, no necesitas rotar una clave válida simplemente porque no la guardaste durante su creación.

Guardar la clave de forma segura

Traslada la clave copiada directamente al almacenamiento de secretos utilizado por la integración.

Algunas ubicaciones adecuadas son:

• Un administrador de secretos gestionado.
• La configuración protegida del entorno del servidor.
• Un secreto de implementación cifrado.
• Un gestor de contraseñas utilizado para la recuperación operativa.

No guardes la clave en:

• JavaScript del lado del navegador u otro paquete frontend descargable.
• Un archivo de código fuente público o privado confirmado en un repositorio.
• Una URL o un parámetro de consulta.
• Documentación pública, capturas de pantalla, mensajes de soporte o sistemas de seguimiento de incidencias.
• Registros compartidos de aplicaciones, eventos de analítica o informes de errores.
• Una hoja de cálculo sin cifrar o un chat de equipo normal.

No añadas la clave a un ejemplo de curl que se vaya a copiar en documentación o en un historial de shell compartido con otras personas. Prefiere una variable de entorno como MAILDROPPA_API_KEY.

Usar la clave de API

Envía la clave completa en el encabezado de solicitud HTTP X-API-Key:

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

No la envíes como token Bearer. Maildroppa espera X-API-Key, no Authorization: Bearer ....

La API de producción y su documentación interactiva de OpenAPI están disponibles en:

https://api.maildroppa.com

Haz clic en “View OpenAPI docs” en la página Clave de API para abrir la documentación en una pestaña nueva del navegador. Selecciona allí un endpoint para revisar su método, ruta, parámetros, cuerpo de solicitud, tipo de respuesta y posibles códigos de estado.

Ejemplo de solicitud

El siguiente ejemplo obtiene la primera página de suscriptores. Lee la clave desde una variable de entorno en lugar de incluir el secreto directamente en el comando:

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

Define la variable en el entorno seguro en el que se ejecuta la integración. El método, la ruta, los parámetros de consulta y el cuerpo exactos dependen del endpoint. Copia esos datos de la documentación de OpenAPI en lugar de deducirlos de las acciones disponibles en la aplicación Maildroppa.

Solicitudes con cuerpos JSON

Para una solicitud que envíe JSON, incluye también:

Content-Type: application/json

Por ejemplo, la estructura básica es:

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 y su cuerpo son marcadores de posición. Sustitúyelos por un endpoint documentado y su esquema de solicitud documentado.

A qué puede acceder la clave

La clave funciona únicamente con los endpoints compatibles con la autenticación mediante clave de API. Una página o solicitud utilizada internamente por la aplicación Maildroppa no forma parte automáticamente de la API pública para clientes.

La documentación de OpenAPI muestra la API para clientes compatible. Si una ruta no está documentada para utilizarse con una clave de API, no supongas que la clave puede acceder a ella.

La página Clave de API no ofrece ámbitos ni casillas de permisos por endpoint. Por lo tanto, la clave actual de la cuenta debe tratarse como una credencial de alto valor, aunque una integración utilice un solo endpoint.

Límites de uso

El contrato actual de OpenAPI documenta estos límites para las claves de API:

• API para clientes predeterminada: 300 solicitudes por minuto y 2.000 solicitudes por hora.
• API de eventos en /events: 100 solicitudes por segundo con una capacidad de ráfaga de 500 solicitudes.

Estos límites se aplican a la cuenta de Maildroppa, no de forma independiente a cada script que comparte su clave. Por lo tanto, varias integraciones pueden consumir el mismo límite disponible.

Cuando Maildroppa devuelva 429 Too Many Requests, deja de enviar solicitudes nuevas y respeta el encabezado de respuesta Retry-After cuando esté presente. Usa una cola y un retroceso controlado en lugar de iniciar muchos reintentos en paralelo.

Las políticas de límites pueden evolucionar mientras la API esté en beta. Consulta la información situada en la parte superior de la documentación de OpenAPI antes de diseñar integraciones de gran volumen.

Usar la clave para solicitudes de API de Automation

Una Automation puede iniciarse cuando tu sistema envía un evento personalizado a la API de eventos de Maildroppa.

Cuando configuras un activador de “API request”, Maildroppa utiliza la misma clave de API de la cuenta administrada en esta página. La configuración del activador puede crear la clave cuando no existe y copiar una solicitud curl preparada que contenga la clave completa.

Esto tiene dos consecuencias importantes:

• Rotar o eliminar la clave de la cuenta también afecta a los sistemas que envían eventos personalizados a las Automations.
• Un ejemplo de solicitud de Automation copiado contiene el secreto en el portapapeles, aunque la clave aparezca enmascarada en pantalla.

Antes de rotar o eliminar la clave, incluye todos los activadores de solicitudes de API y todos los remitentes externos de eventos en tu inventario de integraciones.

Restablecer o reemplazar la clave de API

Usa “Rotate API key” cuando necesites restablecer o reemplazar la credencial actual. Maildroppa crea una clave nueva e invalida la anterior como parte de la misma acción.

Usa la rotación cuando:

• La clave pueda haberse expuesto.
• Una persona o proveedor que conocía la clave ya no necesite acceso.
• Tu política de seguridad exija reemplazar periódicamente las credenciales.
• Quieras reemplazar una clave almacenada en una ubicación antigua o insegura.

Haz clic en “Rotate API key” debajo de la clave enmascarada. Maildroppa abre un diálogo de advertencia que explica que la clave existente dejará de poder utilizarse.

Haz clic en “Rotate API key” en el diálogo para continuar o en “Cancel” para conservar la clave actual.

La rotación no tiene periodo de gracia

Después de confirmar la rotación, la clave antigua deja de funcionar inmediatamente. Maildroppa no mantiene válidas la clave antigua y la nueva al mismo tiempo.

Como la cuenta solo tiene una clave, la rotación afecta a todos los servidores, trabajos programados, integraciones, scripts y remitentes de eventos de Automation que la utilicen.

Usa esta secuencia para una rotación planificada:

1. Enumera todas las integraciones que utilizan la clave actual.
2. Prepara el acceso a la configuración de secretos y al proceso de implementación de cada integración.
3. Elige una breve ventana de mantenimiento si es importante mantener el acceso ininterrumpido a la API.
4. Haz clic en “Rotate API key” y confirma la advertencia con “Rotate API key” en el diálogo.
5. Haz clic en “Copy” para copiar la nueva clave completa.
6. Reemplaza inmediatamente el secreto en todas las integraciones.
7. Reinicia o vuelve a implementar los servicios que cargan los secretos solo durante el arranque.
8. Envía una solicitud documentada e inocua para verificar cada integración.
9. Comprueba si hay respuestas 401 Unauthorized de algún servicio olvidado que aún utilice la clave antigua.

Si se cree que la clave actual está comprometida, rótala inmediatamente y acepta la breve interrupción necesaria para actualizar los sistemas legítimos.

Eliminar la clave de API

Elimina la clave cuando la cuenta ya no deba aceptar solicitudes autenticadas mediante una clave de API.

Haz clic en “Delete API key” debajo de la clave enmascarada. Maildroppa abre un diálogo de advertencia que explica que la clave se eliminará permanentemente de la cuenta.

Haz clic en “Delete API key” en el diálogo para eliminarla o en “Cancel” para conservarla.

Después de eliminarla:

• La clave actual deja de funcionar inmediatamente.
• La página vuelve al estado “No API key yet”.
• Las integraciones del servidor que utilicen la clave eliminada ya no pueden autenticarse.
• Los remitentes de solicitudes de API de Automation que utilicen esa clave ya no pueden enviar eventos.

Eliminar una clave no borra suscriptores, campañas, etiquetas, campos, segmentos, Automations ni otros datos de la cuenta. Elimina la credencial utilizada para acceder a los endpoints de API compatibles.

Más adelante puedes hacer clic en “Create API key” para crear una credencial nueva. El valor eliminado no se restaura. Todas las integraciones deben actualizarse antes de poder utilizar la nueva clave.

Restablecer o eliminar: ¿cuál debes elegir?

Elige “Rotate API key” cuando el acceso a la API deba continuar con una credencial nueva.

Elige eliminarla cuando el acceso a la API deba detenerse por completo, al menos por ahora.

Ambas acciones invalidan inmediatamente la clave actual. La rotación crea el reemplazo como parte de la misma acción; la eliminación deja la cuenta sin ninguna clave.

Recomendaciones de seguridad

Mantén las llamadas a la API en tu servidor

Un navegador o una aplicación móvil no pueden mantener de forma fiable un secreto integrado. Un usuario puede inspeccionar la aplicación, los encabezados de solicitud, los mapas de origen o el tráfico de red y extraer la clave.

Si un sitio web o una aplicación necesita activar una acción, envía primero la solicitud a tu propio backend autenticado. Deja que ese backend valide al usuario y llame a Maildroppa con la clave almacenada en el servidor.

Reduce al mínimo la exposición

Proporciona la clave únicamente a los sistemas que la necesiten. No la distribuyas a todos los desarrolladores ni la pegues en varios archivos de configuración locales.

Como la página actualmente administra una sola clave para toda la cuenta en lugar de varias claves con nombre o ámbitos, utiliza un servicio de integración interno o un proxy si varias aplicaciones necesitan un mayor aislamiento entre sí.

Oculta los encabezados de solicitud

Configura los clientes HTTP, proxies inversos, herramientas de observabilidad y sistemas de informes de errores para ocultar X-API-Key. Una solicitud puede funcionar correctamente y aun así filtrar sus credenciales mediante los registros de depuración.

Mantén separados los entornos

No reutilices una clave de producción en desarrollo local, código de ejemplo, capturas de pantalla o fixtures de prueba. Guarda los secretos específicos de cada entorno en almacenes de secretos específicos de ese entorno.

El enlace “View OpenAPI docs” dirige automáticamente a los usuarios de producción a la documentación de la API de producción. Verifica siempre el nombre de host antes de enviar una clave real.

Rota la clave después de cualquier posible exposición

Eliminar un mensaje, un commit del repositorio, una línea de registro o una captura de pantalla no demuestra que nadie haya copiado la clave. Si el valor completo quedó expuesto, rótala.

Gestionar errores de API

Usa el estado HTTP y el cuerpo de respuesta documentado para decidir qué debe hacer la integración.

Algunos casos habituales son:

• 400 Bad Request — La ruta, el parámetro o el cuerpo JSON no cumple el contrato del endpoint. Compara la solicitud con el esquema de OpenAPI.
• 401 Unauthorized — Falta el encabezado X-API-Key, está vacío o es inválido, se ha eliminado o contiene un valor antiguo tras una rotación.
• 403 Forbidden — La clave autenticada no tiene permiso para utilizar esa operación.
• 404 Not Found — La ruta o el recurso referenciado no existe en esta cuenta.
• 429 Too Many Requests — La integración ha alcanzado un límite de uso de la API. Pausa las solicitudes y respeta el encabezado Retry-After cuando esté presente.
• 5xx — Maildroppa no pudo completar la solicitud. Reintenta las operaciones seguras con un retroceso exponencial limitado y registros que excluyan la clave de API.

No reintentes todos los fallos a ciegas. Corrige las respuestas 400, 401, 403 y la mayoría de las respuestas 404 antes de enviar de nuevo la misma solicitud.

Para las solicitudes que modifican datos, confirma el comportamiento de reintento e idempotencia del endpoint antes de repetir automáticamente una solicitud. Un fallo de conexión no siempre demuestra que Maildroppa no haya realizado ningún cambio.

Solución de problemas

“Create API key” sigue visible

Actualmente no existe ninguna clave en la cuenta. Haz clic una vez en el botón y espera a que termine la solicitud.

Si la creación falla, vuelve a cargar la página antes de intentarlo de nuevo. Es posible que otra página o configuración de Automation ya haya creado la clave de la cuenta.

La clave de la página parece demasiado corta

La página muestra intencionadamente solo los primeros cinco caracteres y *****. Haz clic en “Copy” para copiar el valor completo. No envíes el texto enmascarado en una solicitud.

“Copy” no cambia a “Copied!”

Es posible que el navegador haya bloqueado el acceso al portapapeles. Mantén la página en la pestaña activa, permite el acceso al portapapeles si se solicita y vuelve a hacer clic en “Copy”.

No intentes reconstruir la clave a partir del texto enmascarado.

Una solicitud devuelve 401 Unauthorized

Comprueba que:

• El nombre del encabezado sea exactamente X-API-Key.
• El encabezado contenga el valor completo, sin los asteriscos visibles.
• La integración no esté enviando Authorization: Bearer en su lugar.
• No se hayan añadido espacios, comillas ni un salto de línea al secreto.
• Nadie haya rotado o eliminado la clave de la cuenta.
• Se haya reiniciado el servicio si solo lee las variables de entorno durante el arranque.
• La solicitud se envíe al entorno correcto de la API de Maildroppa.

Una integración funciona, pero otra dejó de hacerlo después de la rotación

Probablemente la segunda integración siga utilizando la clave antigua. No existe un periodo de superposición. Actualiza su secreto y reinicia cualquier proceso que almacene en caché la configuración.

La página de OpenAPI funciona, pero un endpoint devuelve 403

No todos los endpoints de la aplicación admiten autenticación mediante clave de API. Usa una operación documentada para la API de clientes y confirma sus requisitos de autenticación en la página de OpenAPI.

Las solicitudes devuelven 429 Too Many Requests

Reduce las ráfagas de solicitudes, pon el trabajo en cola y vuelve a intentarlo después del retraso devuelto por la API. Evita tormentas de reintentos paralelos. Si varias aplicaciones comparten la única clave de la cuenta, coordina su volumen de solicitudes porque comparten los límites de API de la cuenta.

Lista de comprobación de configuración recomendada

Antes de poner una integración en uso habitual, confirma que:

• La clave se almacena únicamente en la configuración de secretos del lado del servidor.
• Las solicitudes utilizan el encabezado X-API-Key.
• La integración utiliza https://api.maildroppa.com en producción.
• Cada método, ruta, parámetro y cuerpo JSON sigue la documentación de OpenAPI.
• Los registros y los informes de errores ocultan la clave.
• Los tiempos de espera y los reintentos limitados están configurados.
• Se supervisan los errores 401, 403, 429 y del servidor.
• Se ha registrado el responsable de la integración.
• Todos los sistemas que comparten la clave de la cuenta están incluidos en el plan de rotación.
• Una clave comprometida puede rotarse rápidamente.

La página Clave de API es deliberadamente pequeña, pero sus acciones afectan a todas las integraciones de API conectadas a la cuenta. Crea la clave solo cuando sea necesaria, mantenla en servidores de confianza y planifica la rotación como un cambio de credencial para toda la cuenta.