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