Planimail REST API ejemplos con Postman --------------------------------------- En esta documentacion se ilustrara como usar la api con el programa Postman Para eso se debera contar con un **planimail_id** y una **APIKEY** , ambos provistos por Planisys. .. note:: En los ejemplos a continuacion, se utilizara ``myplan`` como *planimail_id* y ``a8dkd9Nk`` como *APIKEY/AUTHORIZATION*. El prefijo a utilizar es siempre **https://planimail-app.planisys.net:8443/api/v1/** , y tanto ``planimail_id`` como ``APIKEY`` seran parte de los encabezados: .. image:: postman-1.png Crear un dominio ++++++++++++++++ **Antes** de poder crear un usuario como parte de un dominio, se debe crear un dominio que debe ser valido sintacticamente, y se precisa una password de administracion. .. image:: postman-2.png Obtencion de Aliases ++++++++++++++++++++ Para obtener la resolucion de un alias, se utiliza el metodo **user_alias** en conjuncion con **GET**, p.ej. .. image:: postman-3.png Lista de Dominios +++++++++++++++++ Para obtener la lista de dominios, se debera llamar al metodo **get_domain_list** con **GET** que devuelve la lista de dominios creados: .. image:: postman-4.png Lista de Aliases ++++++++++++++++ Para obtener la lista de usuarios de un dominio, se debera llamar al metodo **alias_list** con **GET** que devuelve la lista de aliases del dominio especificado, p.ej. .. image:: postman-5.png Lista de Usuarios +++++++++++++++++ Para obtener la lista de usuarios de un dominio, se debera llamar al metodo **get_user_list** con **GET** que devuelve la lista de usuarios del dominio especificado, p.ej. .. image:: postman-6.png Obtener la Quota de un usuario ++++++++++++++++++++++++++++++ Para obtener la Quota o cantidad de Megabytes utilizados por un buzon o cuenta de mail, se utiliza el metodo **user_get_quota** con **GET**, p.ej. .. image:: postman-7.png Setear la Quota de un usuario +++++++++++++++++++++++++++++ Para setear la quota de un usuario, set pueden utilizar los metodos **mailbox** o **user_set_quota** Para el metodo **mailbox** con **POST**, ver a continuacion. .. image:: postman-8.png Crear un usuario ++++++++++++++++ Para crear un usuario, es decir un buzon de correo IMAP, se utiliza el metodo **mailbox** con **POST**. .. warning:: El metodo **mailbox**, al igual que **domain** es **idempotente**, es decir se puede ejecutar varias veces y utilizarse para cambiar algun parametro, como p.ej. una password, el nombre, apellido o telefono En este ejemplo se crea un usuario. Se provee ademas del parametro optativo ``phone`` que se puede utilizar en el **Identity Server** para recuperacion de clave, pero debera ser un telefono valido. .. image:: postman-9.png En caso de no ser un telefono valido, aparecera esta respuesta json y no se creara el usuario (o si ya estaba creado, se invalida la llamada): .. warning:: {"msg":"phone 54115278221 is in invalid format"} .. image:: postman-10.png Los parametros obligatorios son: * ``name`` * ``surname`` * ``quotamb`` El parametro ``quotamb`` especifica el espacio disponible para el usuario en *Megabytes* , en este caso 5120 Megabytes que equivalen a 5G. Borrar un usuario +++++++++++++++++ Para borrar un usuario se utiliza el metodo **mailbox** en conjuncion con el metodo HTTP **DELETE**. Por una cuestion de proteccion y seguridad, se debera contar con la clave del usuario, o forzarle una nueva con una llamada anterior a **POST** y luego **DELETE**. .. image:: postman-11.png Agregar alias +++++++++++++ Para agregar un alias, se utiliza el metodo **user_alias** en combinacion con **POST**. .. warning:: El agregado de aliases **user_alias** con **POST** es **aditivo** , es decir **NO** es *idempotente*. Esto significa que cada llamada **agrega** un nueva direccion de mail a una lista, o crea el alias si este no existia previamente. Sin embargo, si la direccion de mail ya existe en la lista de resolucion, no la agrega, teniendo asi un comportamiento *idempotente*. .. image:: postman-12.png En caso de existir un buzon de correo con el mismo nombre que el alias, este metodo no permite crear el alias. P.ej. si existe el usuario prueba@dominio1.com.ar, y se intenta crear un alias de prueba@dominio1.com.ar a otra cuenta , devuelve error 400 .. image:: postman-13.png Borrar Alias ++++++++++++ Para borrar un alias se utiliza el metodo **user_alias** en combinacion con **DELETE**. Esta llamada API puede tener dos objetivos: * borrar un alias completamente * borrar un alias parcialmente, es decir eliminar un mail de la lista de resolucion. En caso de ser el ultimo mail de la lista de resolucion, se eliminara completamente. En caso de querer borrar un alias *completamente*, solo se precisa del parametro ``alias`` En caso de no existir el alias, la API retorna el siguiente mensaje, p.ej.: .. image:: postman-14.png Para poder borrar un alias *parcialmente* se debera especificar el parametro ``resolves`` junto al parametro ``alias`` . .. image:: postman-15.png Metadatos de Usuario ++++++++++++++++++++ Para modificar o consultar metadatos de usuario se utiliza el metodo **user_metadata** en combinacion con **POST** y **GET** respectivamente. Los campos que se permiten setear son: * ``alt_email`` o e-mail alternativo, para poder verificar y recuperar clave * ``phone`` o telefono movil para verificar y recuperar clave o acreditar identidad mediante SMS * ``name`` o nombre de pila para agregar al encabezado **From:** , tomado desde el Webmail * ``surname`` o apellido para agregar al encabezado **From:** , tomado desde el Webmail .. warning:: **No** es necesario setear **TODOS** los campos, se pueden setear individualmente o en grupos .. image:: postman-16.png Alias de Dominio ++++++++++++++++ Para las operaciones de consulta, creacion y borrado de aliases de dominio, se utiliza el metodo **domain_alias** asociado a los metodos HTTP **GET**, **POST** y **DELETE** respectivamente. El parametro que representa al alias es ``alias_domain`` , y el parametro que representa al dominio al cual resuelve, es ``domain``. En caso de ejecutar **POST** sobre un alias de dominio existente, se sobreescribe el resultado. Ejemplo de creacion: .. image:: postman-17.png Ejemplo de consulta: .. image:: postman-18.png Ejemplo de borrado: .. image:: postman-19.png