Documentation de l'API

Notre API repose sur REST, elle utilise les commodités liées à HTTP, notamment les verbes (GET, POST, PUT, DELETE, ...) et les codes de réponses associés.

L'URL de base de notre API est: https://protecmail.com/api/v1

N'hésitez pas à nous contacter si aimeriez voir d'autres fonctionnalités implémentées.

Authentification

Chaque requête doit être authentifiée par le header Api-Key qui doit contenir une des clés créés dans votre espace client: Gestion des clés d'API

Exemple curl :


                    $ curl https://protecmail.com/api/v1/ping --header "Api-Key:
                    cdd4fc0a-2b4f-4336-90f8-77c72be60791"


                    {"request_id":"96989778-db33-4e1d-93ac-b2245a393097","success":true,"msg":"pong"}

Réponse

Nous répondons à chaque requête par:

un code HTTP qui correspond au statut de la requete.
un objet JSON de type Response

L'objet JSON Response a la structure suivante:

request_id: identifiant unique de la requête.
success: booléen indiquant si la requête à été réalisée avec succés.
msg: un message complémentaire si nécessaire.
data: des données complémentaires si nécessaire.

Exemple:


                    $curl -vvv https://protecmail.com/api/v1/domain/example.tld/addresses --header "Api-Key:
                    cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"7372ded9-bd12-40bf-ac9e-caf8fbb91d50","success":true,"data":["postmaster","john"]}

Informations du compte

GET https://protecmail.com/api/v1/user

L'objet Json User correspondant à la propriété data de la réponse a la structure suivante:

nic: identifiant Protecmail.
first_name: prénom.
last_name: nom.
email: adresse email.
organisation: société.
tva_intra: numéro de TVA intracommunautaire.
address: adresse.
city: ville.
country: pays.
phone: téléphone.

Exemple:


                    $ curl -vvv https://protecmail.com/api/v1/user --header "Api-Key:
                    cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"af07b9b1-25c5-4690-ac1e-4240e5e66e26","success":true,"data":{"nic":"XX-42","first_name":"John","last_name":"Doe","email":"john@doe.com","organisation":"jd
                    unlimited","tva_intra":"FR454545","address":"69 avenue de le
                    pie","city":"Paris","zip":"75010","country":"FR","phone":"+3365478945"}}

Edition du compte

PUT https://protecmail.com/api/v1/user

Le corps de la requête doit contenir l'objet User modifié.

L'objet User a la structure suivante:

nic: identifiant Protecmail.
first_name: prénom.
last_name: nom.
email: adresse email.
organisation: société.
tva_intra: numéro de TVA intracommunautaire.
address: adresse.
city: ville.
country: pays.
phone: téléphone.

Exemple:


                    $ curl https://protecmail.com/api/v1/user
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    --header "Content-Type: application/json"
                    --request PUT
                    --data '{"first_name":"John","last_name":"Doe","email":"john@doe.com","organisation":"jd
                    unlimited","tva_intra":"FR454545","address":"69 avenue de le pie qui
                    chante","city":"Paris","zip":"75010","country":"FR","phone":"+3365478945"}'
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"7671a1f7-a7c4-4e3c-8575-a3e5e211fb9b","success":true}

Liste des factures

GET https://protecmail.com/api/v1/invoices

L'objet JSON retourné dans la propriété data est un tableau d'élements {"date","ref", "total"}

Exemple:


                    $ curl https://protecmail.com/api/v1/invoices
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"15172f05-20fa-4dcd-acd7-7a59d7bf54be","success":true,"data":[{"ref":5,"date":"2018-10-16T17:04:41+02:00","total":60},{"ref":4,"date":"2018-10-16T15:25:08+02:00","total":720},{"ref":3,"date":"2018-10-15T16:08:04+02:00","total":720},{"ref":1,"date":"2018-10-30T14:36:52.897435613+01:00","total":724.8}]}

Télécharger une facture

GET https://protecmail.com/api/v1/invoices/{reference}

Exceptionnellement la réponse est un fichier PDF.

Exemple:


                    $ curl https://protecmail.com/api/v1/invoices/26589
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"15172f05-20fa-4dcd-acd7-7a59d7bf54be","success":true,"data":[{"ref":5,"date":"2018-10-16T17:04:41+02:00","total":60},{"ref":4,"date":"2018-10-16T15:25:08+02:00","total":720},{"ref":3,"date":"2018-10-15T16:08:04+02:00","total":720},{"ref":1,"date":"2018-10-30T14:36:52.897435613+01:00","total":724.8}]}

Réservoirs de jetons de filtrage

Cette ressource vous permet de connaitre le nombre de jetons de filtrage associé à votre abonnement.

GET https://protecmail.com/api/v1/tanks

L'objet JSON retourné dans la propriété data est un tableau contenant les élèments:

monthly: réservoir contenant le reste des jetons de filtrage versés le 1 du mois.
perm: réservoir permanent contenant les jetons non consommés les mois précédents et les jetons achetés séparemnet.
total: la somme des deux réservoirs.

Exemple:


                    $ curl https://protecmail.com/api/v1/tanks
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"9d9866dd-3bc1-4c97-92aa-a27ae812b3b6","success":true,"data":{"monthly":132925,"perm":11086036,"total":11218961}}

Consommation moyenne par jour

Cette ressource vous permet de connaitre la consommation moyenne de jetons par jour.

Elle est calculée sur les 30 dernier jours.

GET https://protecmail.com/api/v1/token/daily-average

La consommation moyenne est liée à la propriété data de la réponse.

Exemple:


                    $ curl https://protecmail.com/api/v1/token/daily-average
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"7c4fa265-3287-402e-8f69-1d76c166cfca","success":true,"data":1263}

Lister les domaines

GET https://protecmail.com/api/v1/domain/all

Exemple:


                    $ curl -vvv https://protecmail.com/api/v1/domain/all --header "Api-Key:
                    cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"5b464d9c-0888-4503-92d4-6c2119370140","success":true,"data":["protecmail.com","protecmail.ch","an.tisp.am","wat.tf","goto.pm","truc.tech","test.com"]}

Informations sur un domaine

GET https://protecmail.com/api/v1/domain/{domain}

La propriéte data de la réponse est un objet JSON Domain ayant la structure suivante:

domain: le nom de domaine. Exemple protecmail.com.
redirectTo: l'adresse IP ou le nom d'hôte correspondant au serveur mail vers lequel on doit transmettre les mails aprés traitement.
spamAction: l'action a réaliser si un mail est classifié comme spam. Les choix possibles sont:
- 0 (défaut): le mail est mis en quarantaine.
- 1: le mail est tagué puis distribué normalement.
Note: cette option n'est pas disponible sur l'offre Free.
virusAction: l'action a réaliser si un mail est classifié comme virus. Les choix possibles sont:
- 0 (défaut): le mail est mis en quarantaine.
- 1: le mail est tagué puis distribué normalement.
Note: cette option n'est pas disponible sur l'offre Free.
sendResume: un booléen qui spécifie si les mails de résumés doivent être envoyés. Note: cette option n'est pas disponible sur l'offre Free.
resumeTemplateSubject: définit le template du sujet du mail de quarantaine. Uniquement sur l'offre Agency.
resumeTemplateBody: définit le template du corps du mail de quarantaine. Uniquement sur l'offre Agency.
resumeTemplateResume: définit le template utilisé pour chaque mail mis en quarantaine. Uniquement sur l'offre Agency.
resumeLinkHostname: nom d'hôte à utiliser pour générer les liens de récupération du mail de résumé de quarantaine. Uniquement sur l'offre Agency.
resumeReplyTo: adresse mail à utiliser comme adresse d'expéditeur pour les mails de résumés. Uniquement sur l'offre Agency.

Exemple:


                    $ curl https://protecmail.com/api/v1/domain/protecmail.com --header "Api-Key:
                    cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "4888a255-50c8-4374-95e6-48581f2f967f",
                    "success": true,
                    "data": {
                    "domain": "protecmail.com",
                    "redirectTo": "in.mail.protecmail.com",
                    "spamAction": 0,
                    "virusAction": 0,
                    "sendResume": true
                    }

Ajouter un domaine

POST https://protecmail.com/api/v1/domain/{domain}

Le corps de la requête doit contenir un JSON représentant un objet Domain (voir au dessus).

Exemple:


                    $ curl https://protecmail.com/api/v1/domain/protecmail.fr
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    --header "Content-Type: application/json"
                    --request POST
                    --data '{
                    "domain": "protecmail.fr",
                    "redirectTo": "aspmx.l.google.com",
                    "spamAction": 0,
                    "virusAction": 0,
                    "sendResume": true
                    }'
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "99c73106-a84d-4058-879b-ed3c7873cbb3",
                    "success": true
                    }

Mettre à jour un domaine

PUT https://protecmail.com/api/v1/domain/{domain}

Le corps de la requête doit contenir un JSON réprésentant l'objet Domain modifié (voir au dessus).

Exemple:


                    $ curl https://protecmail.com/api/v1/domain/protecmail.fr
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    --header "Content-Type: application/json"
                    --request PUT
                    --data '{
                    "domain": "protecmail.fr",
                    "redirectTo": "in.mail.protecmail.com",
                    "spamAction": 0,
                    "virusAction": 0,
                    "sendResume": true
                    }'
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "6df3b97b-7f90-43da-a29f-2eada3ad7d9a",
                    "success": true
                    }

Supprimez un domaine

DELETE https://protecmail.com/api/v1/domain/{domain}

Exemple:


                    $ curl https://protecmail.com/api/v1/domain/protecmail.fr
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    --request DELETE
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "c0616921-bb0b-4a16-8c3f-9dd70df1e2bb",
                    "success": true
                    }

Lister les adresses d'un domaine

GET https://protecmail.com/api/v1/domain/{domain}/addresses

Exemple:


                    $curl -vvv https://protecmail.com/api/v1/domain/example.tld/addresses --header "Api-Key:
                    cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {"request_id":"7372ded9-bd12-40bf-ac9e-caf8fbb91d50","success":true,"data":["postmaster","john"]}

Ajouter une adresse

PUT https://protecmail.com/api/v1/domain/{domain}/addresses/{adresse}

Exemple:


                    $ curl https://protecmail.com/api/v1/domain/protecmail.fr/addresses/postmaster
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    --request PUT
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "c0616921-bb0b-4a16-8c3f-9dd70df1e2bb",
                    "success": true
                    }

Supprimer une adresse

DELETE https://protecmail.com/api/v1/domain/{domain}/addresses/{adresse}

Exemple:


                    $ curl https://protecmail.com/api/v1/domain/protecmail.fr/webmaster
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    --request DELETE
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "bc4572ef-d16c-4410-aa8e-4405a7eaed32",
                    "success": true
                    }

Consulter la quarantaine

GET https://protecmail.com/api/v1/quarantine/{domaine ou adresse}/{début}/{nombre d'enregistrements à retourner}

Les mails en quarantaine sont retournés classés par date d'ajout en quarantaine. Cela signifie par exemple que si vous mettez '0' pour le paramètre début et 10 pour le nombre d'enregistrements', les informations concernant les 10 derniers mails mis en quarantaine vont être retournés.

La propriété data de la réponse va contenir un objet JSON ayant la structure suivante:

emails: la liste des mails mis en quarantaine avec les propriétés suivantes:
- date: date au format RFC3339.
- email: adresse email concernée.
- domain: domaine concerné.
- mailfrom: adresse email de l'expéditeur.
- subject: sujet du mail.
- ident: identifiant du mail. Utilisé pour le re-expédier.
count: nombre de mails en quarantaine pour le domaine ou l'adresse concerné.
nb_pages: nombre de pages en fonction du nombre de mails total et du paramètre 'length'.
current_page: page actuelle.

Exemple:


                    $ curl https://protecmail.com/api/v1/quarantine/protecmail.fr/0/3
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "b2cad76e-2402-4a0a-95e5-84c9640afea5",
                    "success": true,
                    "data": {
                    "emails": [
                    {
                    "date": "2018-06-11T22:49:39+02:00",
                    "email": "xxxx@protecmail.com",
                    "domain": "protecmail.com",
                    "mailfrom": "CanadaExOhrcp@www.Hlawatschek.de",
                    "subject": "Check quality. You will save about 70%. New 10 products weekly. Fast worldwide
                    delivery.",
                    "ident": "11062018224939383525"
                    },
                    {
                    "date": "2018-06-12T00:38:47+02:00",
                    "email": "xxxx@protecmail.com",
                    "domain": "protecmail.com",
                    "mailfrom": "jpierre.tancogne@protecmail.com",
                    "subject": "tancogne are you from ?",
                    "ident": "12062018003847200251"
                    },
                    {
                    "date": "2018-06-11T23:57:56+02:00",
                    "email": "xxxx@protecmail.com",
                    "domain": "protecmail.com",
                    "mailfrom": "ID-343912webmaster@localhost",
                    "subject": "Segue o parecer do seu rastreio 20180077923 Data: 11/06/2018",
                    "ident": "11062018235756594497"
                    }
                    ],
                    "count": 1724,
                    "nb_pages": 575,
                    "current_page": 1
                    }

Débloquer un mail de la quarantaine

GET https://protecmail.com/api/v1/quarantine/{ident}

Réémet un mail mis en quarantaine.

Exemple:


                    $ curl https://protecmail.com/api/v1/quarantine/11062018225433918076
                    --header "Api-Key: cdd4fc0a-2b4f-4336-90f8-77c72be60791"
                    


                    < HTTP/1.1 200 OK
                    

                    {
                    "request_id": "3e144514-ed9d-41b0-aaa4-53f44ddd22cd",
                    "success": true
                    }