Cómo hacer peticiones al API de Mailrelay en Python

¿Usas alguna herramienta de mailing para gestionar tu lista de suscriptores? Mi favorita es Mailrelay y la utilizo en todos mis proyectos en los que manejo una.

¿Por qué uso Mailrelay? Básicamente por las siguientes razones:

• Su servicio técnico es excepcional. Me resuelven todas las dudas que tengo en un espacio breve de tiempo y son muy amables.
• Es muy sencilla de utilizar y tiene todo lo que se le puede pedir a una herramienta de este tipo.
• Su plan gratuito es el mejor que existe en el mercado: te permite enviar hasta 75.000 emails gratis al mes y gestionar hasta 15.000 contactos. Casi nada.
• Y quizá lo más importante junto con su servicio técnico: Se adaptan perfectamente al RGPD.

No, en esta ocasión no te voy a enseñar cómo usar Mailrelay para hacer tus campañas de mailing. Te voy a enseñar algo mejor y que no está en sus manuales: Cómo integrar tu proyecto Python con el API de Mailrelay.

Integrando el API de Mailrelay en tu proyecto Python

Gracias al API de Mailrelay puedes gestionar tu lista de suscriptores desde tu propio código fuente. En mi caso, es frecuente que añada a un usuario de alguna de mis aplicaciones a la lista de suscriptores tras registrarse en la misma.

Lo único malo que tiene la documentación del API es que todos los ejemplos hacen uso del lenguaje PHP 🙃😖

Aunque no es difícil de entender lo que hacen, puede que no sepas cómo traducir estos ejemplos a tu lenguaje favorito: Python 🐍

Pero no te preocupes, a continuación te mostraré un par de casos para usar Python con el API de Mailrelay.

Añadiendo un suscriptor a la lista

En este enlace está la documentación de la operación addSubscriber del API de Mailrelay.

En mi caso, uso la librería requests para hacer las peticiones al API. A continuación te muestro cómo añadir un suscriptor a la lista y a unos grupos determinados:

import logging
import requests

logger = logging.getLogger(__name__)


languages = dict()
languages['es'] = 2
languages['en'] = 3

API_ENDPOINT = "https://<tu_cuenta>.ip-zone.com/ccm/admin/api/version/2/&type=json"


def subscribe_user_to_newsletter(user):
    """
    Este método se utiliza para añadir un nuevo suscriptor a la lista de correo.
    Debe usarse cuando un nuevo usuario se registra.

    Los ids de los grupos de Mailrelay son:

        1: Todos los usuarios
        2: Usuarios lenguaje 'es'
        3: Usuarios lenguaje 'en'

    Args:
        user: Usuario registrado en el sistema

    """

    if current_app.config['APP_ENV'] == current_app.config['APP_ENV_PRODUCTION']:
        language_group = languages.get(user.language, None)
        user_groups = [1]
        if language_group:
            user_groups.append(language_group)
        payload = {
            "function": "addSubscriber",
            "apiKey": current_app.config['MAILRELAY_API_KEY'],
            "email": user.email,
            "name": user.nick,
            "groups[]": user_groups
        }
        try:
            r = requests.post(API_ENDPOINT, data=payload)
            if r.status_code != 200:
                logger.error(u'No se pudo añadir el usuario {} a Mailrelay'.format(user.email))
                return
            else:
                response = r.json()
                if not response or response["status"] == 0:
                    logger.error(u'No se pudo añadir el usuario {} a Mailrelay'.format(user.email))
                    return
                mailrelay_user_id = response.get('data', None)
                logger.info(u'Se añadió el usuario {} a Mailrelay con id: {}'.format(user.email, mailrelay_user_id))
        except Exception:
            logger.exception(u'No se pudo añadir el usuario {} a Mailrelay'.format(user.email))

Recuerda sustituir <tu_cuenta> de la variable API_ENDPOINT por la tuya. También ten presente que debes indicar tu API Key en el parámetro correspondiente. En el ejemplo, este valor lo estoy obteniendo de los parámetros de configuración de mi aplicación. Para acabar, simplemente decirte que añado al suscriptor a la lista en caso de encontrarme en el entorno de producción.

Actualizando un suscriptor de la lista

La actualización de un suscriptor es muy similar. La documentación de la operación updateSubscriber la puedes encontrar aquí. Ten en cuenta que para actualizar un suscriptor necesitas indicar su id, que lo obtienes al añadir el suscriptor a la lista. Si no lo has almacenado, como es mi caso, lo puedes recuperar llamando previamente a la operación getSubscribers:

def update_subscriber(user):
    """
    Este método se utiliza para actualizar los datos de un suscriptor de la lista de correo.
    Debe usarse cuando cambia la información del usuario asociada a la newsletter.

    Los ids de los grupos de Mailrelay son:

        1: Todos los usuarios
        2: Usuarios lenguaje 'es'
        3: Usuarios lenguaje 'en'

    Args:
        user: Usuario a modificar

    """

    if current_app.config['APP_ENV'] == current_app.config['APP_ENV_PRODUCTION']:
        language_group = languages.get(user.language, None)
        user_groups = [1]
        if language_group:
            user_groups.append(language_group)

        # Primero debemos obtener el id del usuario correspondiente a Mailrelay
        payload = {
            "function": "getSubscribers",
            "apiKey": current_app.config['MAILRELAY_API_KEY'],
            "email": user.email
        }
        try:
            r = requests.post(API_ENDPOINT, data=payload)
            if r.status_code != 200:
                logger.error(u'No se pudo recuperar el usuario {} de Mailrelay'.format(user.email))
                return
            else:
                response = r.json()
                if not response or response["status"] == 0:
                    logger.error(u'No se pudo recuperar el usuario {} de Mailrelay'.format(user.email))
                    return
                subscribers = response.get("data", None)
                if not subscribers:
                    logger.warning(u'No se pudo recuperar el usuario {} de Mailrelay'.format(user.email))
                    return
                subscriber_id = subscribers[0]["id"]
        except Exception:
            logger.exception(u'No se pudo recuperar el usuario {} de Mailrelay'.format(user.email))
            return

        # Una vez que se dispone del id del usuario, se invoca al endpoint correspondiente
        # para actualizarlo
        payload = {
            "function": "updateSubscriber",
            "apiKey": current_app.config['MAILRELAY_API_KEY'],
            "id": subscriber_id,
            "email": user.email,
            "name": user.nick,
            "groups[]": user_groups
        }
        logger.info("Actualizando al usuario de Mailrelay {} - Grupos: {}".format(user.email, user_groups))
        try:
            r = requests.post(API_ENDPOINT, data=payload)
            if r.status_code != 200:
                logger.error(u'No se pudo modificar el usuario {} de Mailrelay'.format(user.email))
                return
            else:
                response = r.json()
                if not response or response["status"] == 0:
                    logger.error(u'No se pudo modificar el usuario {} de Mailrelay'.format(user.email))
                    return
                logger.info(u'Se ha modificado el usuario {} de Mailrelay con id: {}'.format(user.email,
                                                                                             subscriber_id))
        except Exception:
            logger.exception(u'No se pudo modificar el usuario {} de Mailrelay'.format(user.email))

Conclusión

Como habrás podido observar, migrar los ejemplos del API de Mailrelay de PHP a código Python es muy sencillo, ¿no te parece? Simplemente tienes que revisar la operación que deseas realizar y hacer uso de la librería requests para hacer las peticiones al endpoint.

Ya sabes que si tienes cualquier duda te puedes poner en contacto conmigo 😉

Vector de ordenador creado por freepik – www.freepik.es