Claves API: cómo crearlas y gestionarlas

Una clave API es un código único que permite que otra aplicación (tu web, tu CRM, tu tienda online o un desarrollo propio) se conecte a tu cuenta de Mailrelay sin usar tu usuario y contraseña. Con ella, esos sistemas pueden añadir suscriptores, enviar emails transaccionales o consultar estadísticas de forma automática.

Necesitarás una clave API si vas a integrar Mailrelay con otra herramienta, si usas un plugin o conector que te la pida, o si tu equipo de desarrollo va a trabajar con la API de Mailrelay. Las claves API están disponibles en todas las cuentas, incluida la cuenta gratuita.

Dónde encontrar las claves API

En tu cuenta de Mailrelay, ve a Configuración > Claves API. En esta sección puedes ver las claves que ya existen, crear nuevas, editarlas y eliminar las que ya no necesites.

En la parte superior de la página encontrarás también un enlace a la documentación de la API, que incluye ejemplos de código para facilitar el trabajo del equipo de desarrollo.

Cómo crear una clave API paso a paso

1. En Configuración > Claves API, haz clic en +Añadir.
2. Se abrirá la página Nueva clave API. En Nombre, escribe un nombre que te ayude a identificar la clave, por ejemplo «CRM» o «Integración web». Este campo es obligatorio.
3. En el desplegable Usuario, elige el usuario de la cuenta al que se asignará la clave.
4. En Caducidad, elige cuándo dejará de funcionar la clave: 7 días, 14 días, 1 mes, 3 meses, 6 meses, 1 año, Sin caducidad o Personalizada. Debajo del campo verás la fecha en que caduca. Si eliges Personalizada, aparece un campo para elegir la fecha y la hora en que la clave dejará de funcionar.
5. En Direcciones IP permitidas, puedes indicar desde qué direcciones se podrá usar la clave: una dirección IPv4 o IPv6, o un rango CIDR. Con +Añadir más se añade otro campo para una dirección más, y con Añadir mi IP se rellena con la dirección IP desde la que estás conectado. Si dejas el campo vacío, se permiten peticiones desde cualquier IP.

6. En Permisos, elige qué puede hacer la clave:
   • Acceso completo: todo lo que puede hacer su usuario, incluidas las áreas que se añadan a la API más adelante.
   • Restringido (recomendado): eliges el acceso para cada área: Contactos, Campañas de email, Email transaccional, SMS, SMS transaccional, WhatsApp, WhatsApp transaccional, Ecommerce, Biblioteca de medios y Webhooks. Todas las áreas empiezan sin acceso. Debajo de cada área se indica qué incluye, y en su desplegable eliges el nivel, por ejemplo Leer o Leer y escribir.
   Por ejemplo, si una integración solo tiene que añadir suscriptores a las listas de tu newsletter o de tus campañas de email marketing, puedes darle acceso solo a Contactos.

7. Haz clic en Crear Clave API.
8. Se abrirá la ventana Clave API creada con tu nueva clave. Cópiala con el botón que aparece junto a ella y guárdala en un lugar seguro. Por seguridad, la clave completa solo se muestra esta vez: cuando cierres la ventana no podrás volver a verla.

9. Haz clic en Cerrar.

La nueva clave aparecerá en el listado. Para cada clave verás su nombre, el usuario al que está asignada, los primeros caracteres de la clave (para que puedas identificarla), su estado, la fecha y hora de caducidad, las direcciones IP permitidas y la fecha del último uso.

Por qué cada clave se asigna a un usuario

Todas las acciones realizadas con una clave API quedan registradas a nombre del usuario al que está asignada. Además, la clave solo puede hacer lo que permitan a la vez sus permisos y su usuario: aunque elijas Acceso completo, nunca podrá hacer más de lo que permite el perfil de ese usuario.

Por eso es recomendable crear un usuario específico para cada integración (por ejemplo, «Integración web» o «CRM»). Así sabrás qué sistema ha hecho cada cambio y podrás gestionar cada integración por separado.

Si necesitas crear ese usuario, consulta Cómo añadir un usuario a la cuenta y Usuarios. Para ver cómo se definen los permisos de cada usuario, consulta Perfiles.

Cómo editar una clave API

En el listado de Configuración > Claves API, haz clic en el botón verde de edición que aparece a la derecha de la clave. Se abrirá la página Editar clave API, con los mismos campos que al crearla: Nombre, Usuario, Caducidad, Direcciones IP permitidas y Permisos. En Caducidad aparece además la opción Mantener la caducidad actual. Cuando termines, haz clic en Actualizar Clave API para guardar los cambios.

Cómo eliminar una clave API

Si una integración ya no se usa o crees que una clave se ha visto comprometida, elimínala desde el listado de Configuración > Claves API con el botón rojo de la papelera que aparece a la derecha de cada clave. El panel te pedirá que confirmes que quieres eliminarla. A partir de ese momento, cualquier sistema que siga usando esa clave dejará de tener acceso a tu cuenta.

Cómo comprobar que la clave funciona

En la documentación de la API, apartado «First request», se explica cómo hacer una primera petición para comprobar que tu clave es válida.

Qué puedes hacer con la API de Mailrelay

Con una clave API puedes automatizar, entre otras cosas:

• Añadir, actualizar o dar de baja suscriptores, y gestionar sus grupos y etiquetas.
• Enviar emails transaccionales, SMS y mensajes de WhatsApp.
• Crear y enviar campañas, y consultar sus estadísticas: aperturas, clics y bajas.
• Gestionar remitentes, campos personalizados e importaciones.
• Recibir avisos automáticos cuando ocurren determinados eventos en tu cuenta.

Así puedes, por ejemplo, conectar tu web o tu tienda online para que los nuevos contactos se añadan solos a la lista de tu newsletter, sin tener que importarlos a mano antes de cada envío masivo de emails.

El envío de emails transaccionales a través de la API requiere el paquete SMTP + API. El resto de endpoints de la API siguen disponibles.

Encontrarás todos los endpoints disponibles, con sus parámetros y ejemplos, en la documentación de la API. También te pueden interesar estos artículos:

• Enviar SMS vía API
• Suscripción a eventos
• ¿Qué son los emails transaccionales? Opciones SMTP y API

Límites de uso de la API

La API tiene límites de peticiones. Los valores vigentes están en la documentación de la API, apartado «Rate limiting».

Buenas prácticas de seguridad

Una clave API da acceso a tu cuenta, así que conviene protegerla igual que una contraseña:

• No la compartas por email ni la incluyas en el código público de tu web.
• Usa una clave distinta para cada integración, asignada a su propio usuario.
• Si una integración no necesita todas las áreas, elige Restringido en Permisos, que es la opción que recomienda el panel, y dale acceso solo a lo que use.
• Guarda las claves en un gestor de contraseñas o en la configuración segura de tu servidor.
• Si crees que una clave se ha visto comprometida, crea una nueva, actualiza tus integraciones y elimina la anterior.
• Revisa de vez en cuando el listado y elimina las claves que ya no uses.

Preguntas frecuentes

He perdido mi clave API, ¿puedo recuperarla?

No. Por seguridad, la clave completa solo se muestra al crearla. Crea una nueva clave, actualiza con ella las integraciones que usaban la anterior y elimina la clave antigua del listado.

¿Puedo usar la API con la cuenta gratuita?

Sí. La sección Claves API está disponible también en la cuenta gratuita. Para enviar emails transaccionales a través de la API necesitas el paquete SMTP + API.

¿Puedo tener varias claves API?

Sí. Puedes crear varias claves y asignar cada una a un usuario distinto de la cuenta.

¿Puedo limitar lo que hace una clave API?

Sí. Al crear o editar la clave, en Permisos elige Restringido y da a cada área solo el acceso que necesite. También puedes indicar en Direcciones IP permitidas desde qué direcciones se podrá usar.

¿Puedo cambiar la caducidad de una clave que ya he creado?

Sí. En la página Editar clave API, elige una nueva opción en Caducidad, o deja Mantener la caducidad actual si no quieres cambiarla.

¿Dónde encuentro el dominio de mi cuenta?

Es el dominio que aparece en la barra del navegador cuando entras en tu panel de Mailrelay, por ejemplo tuempresa.ipzmarketing.com.