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.

Nota

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:

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.:

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.

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:

{"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:

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.

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.

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.

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.

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.

Aviso

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.

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):

Aviso

{«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.

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.

Aviso

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:

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:

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.

Aviso

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.:

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:

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

Aviso

No es necesario setear TODOS los campos, se pueden setear individualmente o en grupos

Ejemplo de consulta:

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):

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:

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:

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:

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"}

Last Updated on 2023-02-14