Création des accès à l’API

L’authentification à l’API se présente par identifiant/mot de passe.
Toute personne ou programme voulant communiquer avec l’API MyZimbra.net doit disposer d’un couple identifiant/mot de passe.

Vous pouvez demander la création d’identifiant à l’API depuis votre espace client en cliquant sur le lien suivant: https://shop.MyZimbra.net
Pour chaque identifiant, vous pouvez sélectionner la liste des domaines sur lesquels il pourra agir.

Demander un token d’authentification à l’API

Maintenant que vous possédez vos identifiants de connexion à l’API, vous pouvez demander à MyZimbra.net un token afin de réaliser les requêtes à l’API.

Pour ce faire, vous devez faire un appel à l’url de l’API https://api.myzimbra.net/api/v1/auth en spécifiant dans le corps de votre requête vos identifiants au format json.

Exemple cURL :

curl -X POST -H 'Content-type: application/json' -H 'Accept: application/json' "https://api.myzimbra.net/api/v1/auth" -d '{"login":"JonSnow","password":"winteriscoming"}'

Réponse de l’API :

{"status":"ok","from":"/api/v1/auth","data":{"session":{"life_time":432000,"idle_time":12000,"token":"WmNbSNDByPUaN7VKmbP7QUF6pd8dO02sdqfvdfsBHeI71k69W9T64lNjH9ZVsKnjPQ35eAmx2+IUGFQEIUVVeyJQ=="},"user":{"login":"JonSnow","email":"jonsnow@castleblack.com"}}}

Important:
votre token a une durée de vie que vous pouvez récupérer via l’attribut life_time et une durée de timeout (durée maximum d’attente entre 2 requêtes autorisée) que vous pouvez récupérer via l’attribut idle_time.

Structure d’une requête

Toutes les requêtes à l’API se font via le protocole HTTP.
Elles sont conçues selon le modèle REST et utilisent les méthodes POST, GET, PUT et DELETE.

POST : Création
GET : Lecture
PUT : Modification
DELETE : Suppression

Chaque action de l’API MyZimbra.net dispose d’une route HTTP spécifique sur une méthode HTTP dédiée.
Exemple:

• Lister des comptes de messagerie: https://api.myzimbra.net/api/v1/accounts/{domain} :: GET
• Créer un compte de messagerie: https://api.myzimbra.net/api/v1/accounts :: POST
• Supprimer un compte de messagerie: https://api.myzimbra.net/api/v1/accounts/{account} :: DELETE

Après authentification à l’API, il vous faut rajouter le token dans l’entête de vos requêtes.

Exemple cURL:

curl -X GET -H 'Content-type: application/json' -H 'Accept: application/json' -H 'Authorization: Token token=WmNbSNDByPUaN7VKmbP7QUF6pd8dO02sdqfvdfsBHeI71k69W9T64lNjH9ZVsKnjPQ35eAmx2+IUGFQEIUVVeyJQ==' "https://api.myzimbra.net/api/v1/domains"

Structure d’une réponse

L’API MyZimbra.net renvoie pour toutes ses requêtes une réponse au format JSON.
Les réponses JSON de l’API MyZimbra.net sont structurées de la manière suivante:

status : Pour indiquer si la requête a rencontré une erreur
from : url d’origine de la requête
data : l’objet réponse de l’API
message : information complémentaire de l’API
code : code erreur généré par l’API

Réaliser votre premier appel

Nous avons vu comment s’identifier et comment structurer nos requêtes HTTP à l’API MyZimbra.net,
nous allons voir maintenant comment réaliser 2 requêtes simples:

1. Lister l’ensemble des comptes de mon domaine de messagerie
2. Créer un nouveau compte de messagerie pour mon domaine

Lister l’ensemble des comptes de mon domaine de messagerie

Pour lister les comptes de mon domaine de messagerie, il faut utiliser la route suivante:
https://api.myzimbra.net/api/v1/accounts/castleblack.com
en utilisant la méthode GET.

La requête dispose des paramètres suivants:

domain : le domaine que nous voulons interroger
offset : l’index de départ du tableau de résultats
limit : le nombre maximum de résultats à retourner
sortby : l’attribut de tri
sortascending : l’indice croissant ou décroissant de tri

Exemple cURL:

curl -X GET -H 'Content-type: application/json' -H 'Accept: application/json' -H 'Authorization: Token token=WmNbSNDByPUaN7VKmbP7QUF6pd8dO02sdqfvdfsBHeI71k69W9T64lNjH9ZVsKnjPQ35eAmx2+IUGFQEIUVVeyJQ==' "https://api.myzimbra.net/api/v1/accounts/castleblack.com?offset=0&limit=100&sortby=name&sortascending=1"

Créer un nouveau compte de messagerie pour mon domaine

Pour créer un compte de mon domaine de messagerie, il faut utiliser la route suivante:
https://api.myzimbra.net/api/v1/accounts
en utilisant la méthode POST.

La requête dispose des paramètres obligatoires suivants:

name : Adresse email du nouveau compte
password : Mot de passe de connexion du compte

Exemplme cURL:

curl -X POST -H 'Content-type: application/json' -H 'Accept: application/json' -H 'Authorization: Token token=WmNbSNDByPUaN7VKmbP7QUF6pd8dO02sdqfvdfsBHeI71k69W9T64lNjH9ZVsKnjPQ35eAmx2+IUGFQEIUVVeyJQ==' "https://api.myzimbra.net/api/v1/accounts" -d '{"name":"samwell@castleblack.com","password":"************"}'

Documentation complète de l’API

MyZimbra.net met à disposition une documentation complète de l’API à l’adresse suivante:
https://documentation-api.myzimbra.net/

Chaque requête est décrite et expliquée de sorte à faciliter l’utilisation de l’API.