Documentation developpeurs Protecmail

API V1

Sommaire

Description

Ce document décrit les services disponibles via les web-services SOAP Protecmail.

Le wsdl: https://soap.protecmail.com/ws_protecmail.wsdl

Utilisation

Méthode d’authentification

L’authentification est réalisée via HTTP AUTH, ce qui signifie que vous devez passer votre login est votre mot de passe au serveur lors de la connexion.

Pour l’implémentation consulter la documentation de la librairie/classe que vous utilisez pour créer votre client SOAP.

Sous PHP5 par exemple, il suffit de transmettre le login et le mot de passe lors de la création du nouvel objet client SoapClient:

$client = new SoapClient('https://soap.protecmail.com/ws_protecmail.wsdl',array('login'=> "Votre_Login",'password'=> "Votre_mot_de_passe",'exceptions'=>'1'));

Gestion des erreurs

En cas d’erreur le serveur génère une erreur SOAP standard :

<?xml version=“1.0” encoding=“UTF-8”?>

  SOAP-ENV:Body
    SOAP-ENV:Fault
      SOAP-ENV:Server
      MESSAGE D’ERREUR
    /SOAP-ENV:Fault
  /SOAP-ENV:Body
/SOAP-ENV:Envelope

Exemples

PHP5

Obtenir le quota consommé d’un domaine

$login='votre_login';
$passwd='votre_mot_de_passe';
$domain='votre_domaine';

$client = new SoapClient('https://soap.protecmail.com/ws_protecmail.wsdl',array('login'=> $login,'password'=> $passwd,'exceptions'=>'1'));
$used_quota=$client->getDomUsedQuota($domain);
print "Le quota consommé est $used_quota <br>";

Methodes

Statistiques et quota

int getGlobalStats(string domain|address,int timestamp_start, int timestamp_stop)

Retourne le nombre de mails scannés pour l’adresse address, ou le domaine domain entre les timestamps UNIX timestamp_start et timestamp_stop.

Limitations:

  • timestamp_start ne doit pas être plus vieux que 30 jours.


int getSpamsStats(string domain|address, int timestamp_start, int timestamp_stop)

Retourne le nombre de spams détectés pour l’adresse address ou le domaine domain entre les timestamps UNIX timestamp_start et timestamp_stop.

Limitations:

  • timestamp_start ne doit pas être plus vieux que 30 jours.


int getVirusStats(string domain|address, int timestamp_start, int timestamp_stop)

Retourne le nombre de virus détectés pour l’adresse address ou le domaine domain timestamps UNIX timestamp_start et timestamp_stop.

Limitations:

  • timestamp_start ne doit pas être plus vieux que 30 jours.


array getVirusList(string domain|address, int timestamp_start,int timestamp_stop)

Retourne un tableau présentant le noms des virus detéctés et leurs occurences pour le domaine domain ou l’adresse address entre les timestamps UNIX timestamp_start et timestamp_stop.

Retour:

  • Le tableau retourné est de la forme : array(array(‘virus name’,‘count’), array(‘virus name’,‘count’),…)

Limitations:

  • timestamp_start ne doit pas être plus vieux que 30 jours.


int getDomUsedQuota(string address|domain)

Retourne le nombre de mails scannés pour l’adresse address ou le domaine domain sur les 30 derniers jours. Correspond au quota consommé.


int getDomAuthorizedQuota(string domain)

Retourne le quota autorisé du domaine, c’est a dire le nombre de mails scannés autorisés sur 30 jours pour le domaine domain.


array getDomTopConso(string domain, int max_return=10)

Variables:

  • string domain: Domaine concerné.

  • int max_return: Nombre maximum d’adresses à retourner (10 par défaut).

Retourne un tableau des adresses pour lesquelles on a filtré le plus de mails sur les trente derniers jours.

Le tableau est classé par ordre décroissant et comporte pour chaque adresse le nombre de mails filtrés sur trente jours.


int gMaxGetUsedQuota()

Retourne le nombre total de mails scannés pour votre abonnement Gateway MAX, sur les 30 derniers jours.

Correspond au quota consommé.


int gMaxGetAuthorizedQuota()

Retourne le quota autorisé de votre abonnement Gateway MAX

Autrement dit le nombre de mails scannés autorisés sur 30 jours pour l’ensemble des domaines rattachés à votre Abonnement Gateway MAX.



Configuration des domaines


Array getProtectedDomains()

Retourne les domaines filtrés.

Valeurs de retour:

  • array ( (type_d_abonnement1)=> tableau(domaine1,domaine2,….),(type_d_abonnement2)=> tableau(domaine4,domaine3,….),…)

Les types d’abonnement sont les suivants :

  • gmax: tous les domaines de votre Gateway MAX
  • gmaxtest: tous les domaines de votre abonnement Gateway MAX qui sont actuellement en test (voir la fonction addTestDomain)
  • g50: tous les domaines lies aux Gateway 50
  • g100: tous les domaines lies aux Gateway 100
  • g500: tous les domaines lies aux Gateway 500


boolean addTestDomain(string domain, boolean auto_transfert)

Cette fonction permet de tester (ou de faire tester) gratuitement notre solution de filtrage sur un domaine. Le test est limité :

  • A une période de 30 jours.
  • A 50 000 mails maximum.

Paramètres:

  • string domain: le domaine à filtrer.
  • boolean auto_transfert: Si vous possédez un abonnement Gateway MAX, en passant true pour ce paramètre, le domaine en test est automatiquement basculé vers le gateway MAX au bout de 30 jours ou si le quota de 50 000 mails et dépassé. Attention, lors de la bascule toutes les statistiques du domaine seront supprimés.

Valeurs de retour: Boolean True en cas de succès, sinon une exception est levée.


string getMX(string domain)

Retourne un tableau contenant les MX vers lesquels le domaine domain doit être configuré au niveau DNS.

Valeurs de retour: array(priorité => MX_HOSTNAME, priorité => MX_HOSTNAME)


string getMXRedirect(string domain)

Retourne l’adresse IP ou le nom d’hôte vers lequel on redirige les mails du domaine domain après filtrage.


boolean setMXRedirect(string domain, string host)

host est l’adresse IP ou le nom d’hôte du serveur vers lequel seront redirigés les mails du domaine domain après traitement.

Valeurs de retour :

  • true: le paramétrage à été changé.
  • false: la configuration du domaine n’a pas changé. Par exemple si le domaine été déjà configuré sur la même valeur de “host”.

Attention: Il faut attendre quelques minutes avant que cette nouvelle configuration soit effective.


array getAllowedUsers(string domain)

Retourne un tableau contenant les utilisateurs autorisés pour le domaine domain.

Un utilisateur est défini par la chaîne qui précède l’arobase dans une adresse émail. Par exemple, toto pour toto@domaine.com.

Ainsi si vous exécutez:

getAllowedUsers(“domaine.com”)
et que le résultat est :
array (“riri”,“fifi”,“loulou”)
Cela signifie que les seules adresses valides du domaine sont riri@domaine.com, fifi@domaine.com et loulou@domaine.com

Tout mails dont le destinataire n’est pas dans cette liste sera refusé par notre plate-forme de filtrage.

Par défaut, tous les utilisateurs/destinataires sont acceptés. Et le tableau retourné sera :

 array(‘all’) 


boolean addAllowedUsers(string domain, array users)

Ajoute les utilisateurs contenu dans le tableau users aux destinataires valides pour le domaine domain.


boolean delAllowedUsers( string domain, array a_users)

Supprime les utilisateurs contenu dans le tableau a_users aux destinataires valides pour le domaine domain.


boolean allowAllUsers(string domain)

Autorise tous les destinataires possible du domaine domain.


string getInstallStatut(string domain)

Retourne le status d’installation/configuration du domaine domain sur notre plate-forme de filtrage.

Valeurs de retour:

  • PENDING: le domaine est en attente de configuration.
  • DONE: le domaine est configuré.
  • NOT_FOUND: le domaine n’a pas été trouvé (ne devrait pas arriver).

Filtrage

boolean setPostScanAction(string domain, int spamaction, int virusaction)

Définit l’action à prendre en cas de détection de virus ou de spam pour le domaine domain.

Valeur de retour: retourne true si l’enregistrement à été modifié.

Valeurs possibles de spamaction:

  • 1: Le mail est mis en quarantaine(par défaut).
  • 2: Le mail est marqué (tag dans le sujet et dans les headers) puis distribué normalement.

Valeurs possibles de virusaction:

  • 1: Le mail est détruit(par défaut).
  • 2: Le mail mail est marqué (tag dans le sujet et dans les headers) puis distribué normalement.


array getPostScanAction(string domain)

Retourne les actions à réaliser en cas de détection de spam ou de virus pour le domaine domain.

Valeur de retour: la valeur retournée est un tableau, le premier élément (int) concerne l’action à réaliser concernant les spams, le second (int) concerne l’action à réaliser en cas de détection de virus.

Valeurs possibles de flag:

  • 0: Traitement normal (quarantaine pour les spams, rejet pour les virus).
  • 1: Le mail mail est marqué (tag sujet et header) puis distribué normalement.


array getFilter(string domain|address, int type)

Retourne un tableau contenant les filtres personnels pour l’adresse ou le domaine sous la forme [id,user,ou,quoi],[…

Le parametre type (int 0|1) permet de sélectionner la blackliste(0) ou la whitelist(1)


boolean addFilter(string domain|address, int type, string search_field, string search_what)

Permet d’ajouter un filtre personnalisé.

Paramètres:

  • string domain|adress: le domaine ou l’adresse concernée.
  • string search_field: le champs de recherche. les valeurs possibles sont: subject (le sujet), from (le champ From:) ou header (la recherche se fait dans tous les headers).
  • string what: ce qu’il faut rechercher, soit une chaîne ou une expression régulière. Pour que le scanner utilise les expressions régulières il faut préfixer la chaîne avec [regex].
  • int type: définis si il s’agit d’un filtre de blackliste (0) ou de whiteliste(1)

Limitations:

  • La chaîne search_what ne doit pas dépasser 244 caractères, dans le cas contraire elle sera tronquée a cette limite.
  • Il est impossible de créer plus de 20 règles par domaines.(somme des règles de blackliste et de whiteliste pour l’ensemble du domaine, les règles portant sur une adresse sont comptabilisées comme une règle pour le domaine).


boolean delFilter(string domain, int filter_id)

Supprime un filtre.

Paramètres:

  • string domain: le domaine concerné (Attention si le filtre est liée a une seule adresse il faut quand meme mettre le domaine et pas l’adresse).
  • int id_filter: identifiant du filtre retourné par getFilter.


boolean reportSpam(string spam)

Permet de reporter un spam.

Paramètre: - string spam: la source complète du spam a traiter


boolean reportHam(string domain,int spam_id)

Permet de reporter un faux positif.

Paramètre:

  • string domain: le domaine concerné par ce report (ie le domaine qui a eu un problème de faux positif).
  • int spam_id: identifiant de quarantaine du faux positif (retourné par getQuarantaine)



Quarantaine

int getQuarantaineCount(string domain|address)

Retourne le nombre de mails en quarantaine pour le domaine domain ou l’adresse address.


array getQuarantaine(string domain|adress, [timestamp start, timestamp stop=now(), int $limit=100])

Retourne le détail de la quarantaine pour le domaine domain ou l’adresse address.

Valeurs de retour :

  • array(Qarray(),Qarray(),Qarray()) chaque Qarray represente un mail en quarantaine de la façon suivante : Qarray=(id_mail=>‘id’, date=>‘date’, subject=>‘subject’,mail_from=>‘expediteur’,rcpt_to=>‘destinataire’)


boolean resendFromQuarantaine(string domain_or_address, string id_mail)

Debloque de la quarantaine le mail ayant pour identifiant id_mail et ayant comme destinataire domain_or_address. domain_or_address est l’adresse mail ou le domaine du destinataire

id_mail ayant été récupéré via la fonction getQuarantaine().



Gateway MAX

boolean gMaxAddDomain(string domain)

Ajoute le domaine domain à votre abonnement Gateway MAX.

Attention: si vous ajoutez un domaine qui n’a pas encore d’enregistrement MX déclaré ou si le MX est déjà configuré vers notre plate-forme vous devez impérativement utiliser ensuite la fonction setMXRedirect(string domain, string host), sinon vos domaines ne seront pas configurés et tous les mails nous parvenant a destination de ce domaine seront refusés.

Limitations:

  • L’abonnement Gmax utilisé est celui correspondant à l’utilisateur authentifié.


boolean gMaxDelDomain(string domain)

Supprime le domaine domain de votre abonnement Gateway MAX.



Mail de résumés des mails en quarantaine

string getQuarantineSummaryBodyTemplate(string domain)

Retourne le template utilisé pour le corps des mails de résumé de quarantaine du domaine domain.


boolean setQuarantineSummaryBodyTemplate(string domain, string template)

Définit le template utilisé pour le corps des mails de resumé de quarantaine pour le domaine domain.

Vous pouvez utiliser au sein de vos templates plusieurs variables :

  • [%MAIL%] : adresse mail concernée

  • [%DATE%] : date actuelle

  • [%DATE_END%] : date de conservation des mails en quarantaine

  • [%TOTAL_STOPPED%] : Nombre de mail stoppes au cours des 24 dernières heures

  • [%RESUME%] : le résumé des mails qui peut être lui aussi modifié via la fonction setQuarantineSummarySubTemplate (voir ci-dessous).

Limitations :

  • Votre template doit au moins contenir la variable [%RESUME%].
  • La taille maximum du template doit être de 5 000 caractères.

Le template par défaut est:

Bonjour,

Voici la liste des mails mis en quarantaine au cours des 24 dernières heures. Ces mails resteront en quarantaine jusqu’au : [%DATE_END%]

[%RESUME%]

Bonne journée,


string getQuarantineSummarySubjectTemplate(string domain)

Retourne le template du mail de résumé de quarantaine du domaine domain.


boolean setQuarantineSummarySubjectTemplate(string domain, string template)

Définit le template du sujet du mail de résumé de quarantaine.

Le template par défaut est :

Résumé de vos mails en quarantaine : [%TOTAL_STOPPED%] mails stoppés pour votre adresse [%MAIL%] [%DATE%].

Limitations : - La taille maximum de ce template est de 250 caractères.


string getQuarantineSummarySubTemplate(string domain)

Ce template représente la variable [%RESUME%] du template principal.

Valeur par défaut :

Sujet: %s \r\nExpediteur: %s \r\nPour le récupérer cliquez sur le lien : mailto:quarantine-%s@%s\r\nOu envoyez un mail a l’adresse quarantine-%s@%s\r\n\r\n”


boolean setQuarantineSummarySubTemplate(string domain, string template)

Permet de définir la variable [%RESUME%] du template principal.


string getQuarantineSummaryReplyTo(string domain)

Retourne l’adresse email utilisée comme “Reply To” pour générer les mails de résumé de quarantaine du domaine domain*.

Attention: Si vous désirez personnaliser cette adresse et que vous n’avez pas definit les adresses valides d’un domaine, il y a de forte chance que cette adresse reçoive de nombreux bounces si de votre coté vous bouncez les mails destinés à des adresses qui n’existent pas.


boolean setQuarantineSummaryReplyTo(string domain, string reply_to)

Définit l’adresse utilisée comme “reply to” pour les mails de résumé de quarantaine du domaine domain.


Retourne le domaine utilisé pour générer les liens de récupération des mails en quarantaine dans le résumé pour le domaine domain.


Definit le domaine utilisé dans les liens de récupération d’un mail en quarantaine.

Cette fonction vous permet de créer des liens de récupération personnalisés qui vont êtres utilisés dans les mails de résumé.

Le domaine utilisé par défaut est pm13.com.

Exemples:

  • Lien par défaut : “Pour le recuperer cliquez sur le lien : mailto:quarantine-xxxxxxxxxxxxx@pm13.com”
  • Lien personalisé : “Pour le recuperer cliquez sur le lien : mailto:quarantine-xxxxxxxxxxxxx@votre_domaine.com”

Attention: Avant de définir un nouveau domaine, vous devez contacter le support afin que l’on fasse la configuration pour ce domaine.


boolean getQuarantineSummaryStatus(string domain)

Retourne true si les résumés de quarantaine sont envoyés pour le domaine domain, retourne false dans le cas contraire.


bolean setQuarantineSummaryStatus(string domain, bolean status)

Définit si l’on doit envoyer les mails de résumé pour le domaine domain.

Si status==true, les résumés seront envoyés.

Si status==false, les résumés ne seront pas envoyés.