Planimail REST API ****************** El sistema de repositorio de mails IMAP llamado **Planimail** provee, ademas de webmail y gestion AVAS, de una **API REST** para poder gestionar las cuentas de e-mail y dominios desde un CRM o Panel de Control propio. Las llamadas API reciben encabezados por un lado, y por el otro datos en formato **JSON** , y a su vez las respuestas llegan en forma de **JSON**. En esta documentacion se ilustrara con el comando de consola **curl** desde *Linux*, *MacOSX* o *Windows*. En *Linux* se puede agregar **| jq** al final de la llamada, para mostrar el JSON de respuesta en formato mas amigable, como se vera en algun ejemplo mas abajo. 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*. 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: Encabezados (Headers) +++++++++++++++++++++ Las llamadas al API REST Planimail precisan de 4 encabezados: * *Content-Type: application/json* * *accept: application/json* * *Authorization: a8dkd9Nk* * *Planimail: myplan* Retornos de llamada API +++++++++++++++++++++++ El codigo de retorno HTTP de las llamadas API es **200** , a menos que se haya omitido algun parametro requerido , o dicho parametro sea invalido (p.ej. un dominio o direccion de mail con sintaxis invalida) en cuyo caso sera **400**. Por otro lado, en el JSON de retorno de llamadas POST o DELETE, se incluye un parametro ``msg`` indicando el status de la operacion. En el caso de las llamadas GET, el JSON es puro retorno de los datos solicitados. 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. En la llamada se deberan enviar los 4 encabezados , y el metodo de peticion HTTP **POST** para creacion o modificacion, y el metodo API **domain** despues del prefijo: .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/domain -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain": "dominio1.com.ar", "admin_password" : "Hr@87978490" }' Con esta llamada se crea un usuario *admin@dominio1.com.ar* con clave *Hr@87978490* y se crean dos aliases hacia la cuenta admin: *postmaster* y *abuse* , dado que dichos aliases son mandatorios en el ambito del correo electronico en Internet. Utilizando el metodo **GET** se puede preguntar si el dominio existe en el Planimail *myplan*, p.ej.: .. code:: bash curl -X GET https://planimail-app.planisys.net:8443/api/v1/domain -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain": "dominio1.com.ar" }' {"msg":"Domain dominio1.com.ar exists in Planimail myplan"} Este metodo **POST** con **domain** ademas es **idempotente**, es decir se puede volver a llamar sobre un dominio existente p.ej. para cambiar la clave del usuario admin. Obtencion de Aliases ++++++++++++++++++++ Para obtener la resolucion de un alias, se utiliza el metodo **user_alias** en conjuncion con **GET**, p.ej. .. code:: bash curl -X GET https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "postmaster@dominio1.com.ar" }' {"msg":"User Alias postmaster@dominio1.com.ar is alias of admin@dominio1.com.ar in Planimail myplan"} En este caso la respuesta es positiva, dado que se encontro el alias y su significado. Pero en caso de no existir el alias, sale el mensaje: .. code:: bash {"msg":"User Alias xyz@dominio1.com.ar does not exist in Planimail myplan"} 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: .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/get_domain_list -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain": "dominio1.com.ar" }' 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. .. code:: bash curl -X GET https://planimail-app.planisys.net:8443/api/v1/alias_list -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain": "dominio1.com.ar" }' 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. .. code:: bash curl -X GET https://planimail-app.planisys.net:8443/api/v1/get_user_list -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain": "dominio1.com.ar" }' 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. .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_get_quota -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "email": "usuario1@dominio1.com.ar" }' 2>/dev/null | jq { "quota_used_MB": 0, "quota_available_MB": 5120, "percentage_used": 0 } 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. En el caso de user_set_quota, se debe proveer el nombre del usuario y la quota deseada en Megabytes, p.ej. .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_get_quota -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "email": "usuario1@dominio1.com.ar", "quotamb": 16384 }' 2>/dev/null | jq { {"msg":"User Mailbox usuario1@dominio1.com.ar successfully modified in Planimail myplan with quota 16384"} } 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. .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/mailbox -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "email": "jbaliza@dominio1.com.ar", "password" : "Hola@Ju8a", "quotamb" : 2048, "name":"Juan", "surname":"Baliza", "phone":"+5491156785678" }' 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"} Los parametros obligatorios son: * ``name`` * ``surname`` * ``quotamb`` El parametro ``quotamb`` especifica el espacio disponible para el usuario en *Megabytes* , en este caso 2048 Megabytes que equivalen a 2G. 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**. .. code:: bash curl -X DELETE https://planimail-app.planisys.net:8443/api/v1/mailbox -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "email": "jbaliza@dominio1.com.ar", "password" : "Hola@Ju8a" }' {"msg":"Mailbox jbaliza@dominio1.com.ar successfully deleted"} 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*. Ejemplo de como funciona la construccion de aliases, con comportamiento **aditivo**: .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "soporte@dominio1.com.ar", "resolves":"jbaliza@dominio1.com.ar" }' {"msg":"User Alias soporte@dominio1.com.ar has been created pointing to jbaliza@dominio1.com.ar in Planimail myplan"} curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "soporte@dominio1.com.ar", "resolves":"jbaliza@gmail.com" }' {"msg":"User Alias soporte@dominio1.com.ar has been created pointing to jbaliza@dominio1.com.ar,jbaliza@gmail.com in Planimail myplan"} Este es un caso en el cual el comportamiento el comportamiento es **idempotente**, es decir como jbaliza@dominio1.com.ar ya existe en la resolucion del alias, no lo agrega: .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "soporte@dominio1.com.ar", "resolves":"jbaliza@dominio1.com.ar" }' {"msg":"User Alias soporte@dominio1.com.ar has been created pointing to jbaliza@dominio1.com.ar in Planimail myplan"} curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "soporte@dominio1.com.ar", "resolves":"jbaliza@dominio1.com.ar" }' {"msg":"User Alias soporte@dominio1.com.ar has been created pointing to jbaliza@dominio1.com.ar in Planimail myplan"} El largo maximo de una resolucion de aliases es 65,535 caracteres. .. warning:: 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: {"msg":"A mailbox prueba@dominio1.com.ar already exists in Planimail myplan"} 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.: .. code:: bash curl -X DELETE https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "xyz@dominio1.com.ar" }' {"msg":"The alias xyz@dominio1.com.ar does not exist in Planimail myplan"} Para poder borrar un alias *parcialmente* se debera especificar el parametro ``resolves`` junto al parametro ``alias`` . P.ej. si *soporte@dominio1.com.ar* resuelve a *jbaliza@dominio1.com.ar* y *jbaliza@gmail.com* , y se quiere eliminar a *jbaliza@gmail.com* de la lista de resolucion, la llamada debera ser: .. code:: bash curl -X DELETE https://planimail-app.planisys.net:8443/api/v1/user_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "alias": "soporte@dominio1.com.ar", "resolves":"jbaliza@dominio1.com.ar" }' {"msg":"User Alias soporte@dominio1.com.ar has been modified in Planimail myplan" } Metadatos de Usuario ++++++++++++++++++++ Para modificar o consultar metadatos de usuario se utiliza el método **user_metadata** en combinación 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 teléfono móvil 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 Ejemplo de consulta: .. code:: bash curl -X GET https://planimail-app.planisys.net:8443/api/v1/user_metadata -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "email": "xyz@dominio1.com.ar" }' { "phone": "+13057896707", "name": "Cuenta1", "surname": "de prueba", "alt_email": "cuenta@outlook.com" } Ejemplo de seteo de 2 campos sobre la llamada anterior (el json de respuesta son los metadatos seteados): .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/user_metadata -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "email": "xyz@dominio1.com.ar", "phone":"+13057890000", "surname":"Testing" }' { "phone": "+13057890000", "name": "Cuenta1", "surname": "Testing", "alt_email": "cuenta@outlook.com" } 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: .. code:: bash curl -X POST https://planimail-app.planisys.net:8443/api/v1/domain_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain_alias": "dominio2.com.ar", "domain":"dominio1.com.ar" }' {"msg":"Domain Alias dominio2.com.ar of dominio1.com.ar created in Planimail myplan"} Ejemplo de consulta: .. code:: bash curl -X GET https://planimail-app.planisys.net:8443/api/v1/domain_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain_alias": "dominio2.com.ar" }' {"msg":"Domain Alias dominio2.com.ar is alias of dominio1.com.ar in Planimail myplan"} Ejemplo de borrado: .. code:: bash curl -X DELETE https://planimail-app.planisys.net:8443/api/v1/domain_alias -H "accept: application/json" -H "Authorization: a8dkd9Nk" -H "Planimail: myplan" -H "Content-Type: application/json" -d '{ "domain_alias": "dominio2.com.ar" }' {"msg":"Domain Alias dominio2.com.ar deleted in Planimail myplan"} .. |date| date:: Last Updated on |date|