Planimail REST API

The IMAP mail repository system called Planimail provides, in addition to webmail and AVAS management, a REST API to manage email accounts and domains from a CRM or your own Control Panel.

API calls receive headers on one side, and data in JSON format on the other, and the responses are also in JSON format.

In this documentation, examples will be shown using the curlconsole command from Linux, MacOSX, or Windows. On Linux,you can add |jq at the end of the call to display the JSONresponse in a more user-friendly format, as shown in some examples below.

For this, you will need a planimail_id and an APIKEY, both provided by Planisys.

Note

In the examples below, myplan will be used as the planimail_id and a8dkd9Nk as the APIKEY.

The prefix to use is always https://planimail-app.planisys.net:8443/api/v1/, and both planimail_id and APIKEY will be part of the headers:

Headers

Calls to the Planimail REST API require 4 headers:

Content-Type: application/json

accept: application/json

Authorization: a8dkd9Nk

Planimail: myplan

API Call Returns

The HTTP return code for API calls is 200, unless a required parameter is omitted, or the parameter is invalid (e.g., a domain or email address with invalid syntax), in which case it will be 400.

Additionally, the JSON returned from POST or DELETE calls includes a msg parameter indicating the status of the operation. For GET calls, the JSON simply returns the requested data.

Create a domain

Before creating a user as part of a domain, you must create a domain that is syntactically valid, and you need an administration password.

The call should include the 4 headers, and use the HTTP POST method for creation or modification, and the domain API method after the prefix:

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

This call creates a user admin@dominio1.com.ar with password Hr@87978490 and creates two aliases for the admin account: postmaster and abuse, as these aliases are mandatory in the context of email on the Internet.

Using the GET method, you can check if the domain exists in Planimail myplan, e.g.:

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

This POST method with domain is also idempotent, meaning it can be called again on an existing domain, e.g., to change the admin user’s password.

Obtaining Aliases

To obtain the resolution of an alias, use the user_alias method in conjunction with GET, e.g.

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

In this case, the response is positive, as the alias and its resolution were found. However, if the alias does not exist, the following message is returned:

{"msg":"User Alias xyz@dominio1.com.ar does not exist in Planimail myplan"}

List of Domains

To obtain the list of domains, call the get_domain_list method with GET to return the list of created domains:

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

List of Aliases

To obtain the list of users in a domain, call the alias_list method with GET to return the list of aliases in the specified domain, e.g.

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

List of Users

To obtain the list of users in a domain, call the get_user_list method with GET to return the list of users in the specified domain, e.g.

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

Get a User’s Quota

To get the quota or the amount of Megabytes used by a mailbox or email account, use the user_get_quota method with GET, e.g.

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
}

Set a User’s Quota

To set a user’s quota, you can use the mailbox or user_set_quota methods. For the mailbox method with POST, see below.

In the case of user_set_quota, you must provide the user’s name and the desired quota in Megabytes, e.g.

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

Create a User

To create a user, i.e., an IMAP mailbox, use the mailbox method with POST.

Warning

The mailbox method, like domain, is idempotent, meaning it can be executed multiple times and used to change parameters, such as a password, first name, last name, or phone number.

In this example, a user is created. The optional phone parameter is provided, which can be used in the Identity Server for password recovery, but it must be a valid phone number.

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

If the phone number is not valid, this JSON response will appear, and the user will not be created (or if it was already created, the call is invalidated):

Warning

{“msg”:”phone 54115278221 is in invalid format”}

The mandatory parameters are:

name
surname
quotamb

The quotamb parameter specifies the space available to the user in Megabytes, in this case 2048 Megabytes, equivalent to 2G.

Delete a User

To delete a user, use the mailbox method in conjunction with the HTTP DELETE method.

For protection and security reasons, you must have the user’s password, or force a new one with a prior POST call, then 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"}

Add Alias

To add an alias, use the user_alias method in combination with POST.

Warning

Adding aliases with user_alias and POST is additive, meaning it is NOT idempotent. This means that each call adds a new email address to a list or creates the alias if it did not already exist. However, if the email address already exists in the resolution list, it will not be added, thus behaving idempotently.

Example of how alias construction works, with additive behavior:

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

This is a case where the behavior is idempotent, meaning since jbaliza@dominio1.com.ar already exists in the alias resolution, it is not added:

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

The maximum length of an alias resolution is 65,535 characters.

Warning

If there is already a mailbox with the same name as the alias, this method does not allow creating the alias. For example, if the user prueba@dominio1.com.ar exists, and you try to create an alias from prueba@dominio1.com.ar to another account, it returns error 400:

{“msg”:”A mailbox prueba@dominio1.com.ar already exists in Planimail myplan”}

Delete Alias

To delete an alias, use the user_alias method in combination with DELETE.

This API call can have two objectives:

delete an alias completely
delete an alias partially, meaning removing an email from the resolution list. If it is the last email in the resolution list, it will be deleted completely.

If you want to delete an alias completely, you only need the alias parameter. If the alias does not exist, the API returns the following message, e.g.:

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

To delete an alias partially, you must specify the resolves parameter along with the alias parameter.

For example, if soporte@dominio1.com.ar resolves to jbaliza@dominio1.com.ar and jbaliza@gmail.com, and you want to remove jbaliza@gmail.com from the resolution list, the call should be:

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

User Metadata

To modify or query user metadata, use the user_metadata method in combination with POST and GET respectively.

The fields that can be set are:

alt_email or alternate email, for verification and password recovery
phone or mobile phone for verification and password recovery or to verify identity via SMS
name or first name to add to the From: header, taken from Webmail
surname or last name to add to the From: header, taken from Webmail

Warning

It is NOT necessary to set ALL the fields; they can be set individually or in groups

Query Example:

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

Example of setting 2 fields in the previous call (the response JSON shows the set metadata):

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

Domain Alias

For domain alias queries, creation, and deletion, use the domain_alias method with the HTTP GET, POST, and DELETE methods respectively.

The parameter representing the alias is alias_domain, and the parameter representing the domain to which it resolves is domain.

If you execute POST on an existing domain alias, the result is overwritten.

Creation Example:

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

Query Example:

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

Deletion Example:

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 2024-08-20