Toute la documentation concernant notre service SOAP

Description

Ce document décrit les services disponibles via les webservices 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 transmetre 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 :

  
    
      SOAP-ENV:Server
      MESSAGE D'ERREUR
    
  

Exemples

PHP5

Obtenir le quota consommé d'un domaine

 $login,'password'=> $passwd,'exceptions'=>'1'));
$used_quota=$client->getDomUsedQuota($domain);
print "Le quota consommé est $used_quota 
";
?>

Methodes/Services accessibles

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 etre 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 etre plus vieux que 30 jours.

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

Retourne le nombre de virus detectés pour l'adresse address ou le domaine domain entre les timestamps UNIX timestamp_start et timestamp_stop.

Limitations:

• timestamp_start ne doit pas etre 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.

Valeur de retour:

• Le tableau retourné est de la forme : array(array('virus name','count'), array('virus name','count'),....)

Limitations:

• timestamp_start ne doit pas etre 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 authorisé du domaine, c'est a dire le nombre de mails scannés authorisé sur 30 jours pour le domaine $domain.

array getDomTopConso(string domain, int max_return=10)

string domain: Domaine concerné.

int max_return: Nombre maximum d'adresse a 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 mail 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 authorisé de votre abonnement Gateway MAX

C'est a dire 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 que vous filtrez via nos services.

Valeurs de retour : Tableau ( (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 Getway 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.

Parametres:

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

Valeurs de retour: Boolean True en cas de succes, sinon une expection est levée.

string getMX(string domain)

Retourne un tableau contenant les MX vers lesquels le domaine domain doit etre 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'hote vers lequel on redirige les mails du domaine domain aprés filtrage.

boolean setMXRedirect(string domain, string host)

Fixe a host l'adresse IP ou le nom d'hote du serveur vers lequel seront redirigés les mails du domaine domain aprés filtrage.

Valeurs de retour :

• true: Le paramétrage à été changé.
• false: La configuration du domaine n'a pas changé. Par exemple si le domaine été deja 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 defini par la chaine qui précede l'arobase dans une adresse email. Par exemple, toto pour toto@domaine.com.

Ainsi si vous executez:

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
• loulou@domaine.com

Tout mails dont le destinataire n'est pas dans cette liste sera refusé par notre plateforme de filtrage.

Par défault, 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 plateforme 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 ete 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 uniquement 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 detruit(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 detection de spam ou de virus pour le domaine domain.

Valeur de retour: La valeur retournée est un array, le premier element (int) concerne l'action a réaliser concernant les spam le second (int) concerne l'action a réaliser en cas de detection 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 personels 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 chaine ou une expression régulière. Pour que le scanner utilise les expressions régulières il faut prtefixer la chaine avec [regex].
• int type: définis si il s'agit d'un filtre de blackliste (0) ou de whiteliste(1)

Limitations:

• La chaine 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 100 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ètre::

• string domain: le domaine concerné (Attention si le filtre est liée a une seule adresse il faut quand meme mettre le domaine ets 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 complete 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 probleme 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 ete recupé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 declaré ou si le MX est deja configuré vers notre plateforme vous devez imperativement 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 resumé 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 concernee

[%DATE%] : date actuelle

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

[%TOTAL_STOPPED%] : Nombre de mail stoppes au cours des 24 dernieres heures

[%RESUME%] : le resume 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 1 000 000 caracteres.

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 :

Resume 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 caracteres.

Sujet: %s \r\nExpediteur: %s \r\nPour le recuperer cliquez sur le lien : mailto:quarantine-%s@%s\r\nOu envoyez un mail a l'adresse quarantine-%s@%s\r\n\r\n"

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

string getQuarantineSummaryQlink(string domain, string quarantaine_summary_link)

Retourne le domaine utilisé pour génerer les liens de récuperation des mails en quarantaine dans le résumé pour le domaine domain.

boolean setQuarantineSummaryQlink(string domain, string quarantaine_link)

Definit le domaine utilisé dans les liens de recuperation d'un mail en quarantaine.

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

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

Exemple :

• 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 definir un nouveau domaine, vous devez contacter le support afin que l'on fasse la configuration pour ce domaine.

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