Das REST API bietet ausschließlich eine generelle Authentisierung ohne Zugriffssteuerung für einzelne Benutzer. Es dient ausschließlich dazu, Requests der REST Frontends zu verarbeiten.

Les requêtes de recherche permettent de retrouver les courriels archivés. Comme tous les courriels, y compris leurs pièces jointes, sont indexés en texte intégral, il est possible de les retrouver en fonction de leur contenu ou de leurs attributs (et bien sûr de toute combinaison d'attributs).

Suchanfragen werden mittels eines HTTP bzw. HTTPS URL aufgerufen. Die Syntax ist dabei grundsätzlich:

http://bennohost:21080/search/{requête de recherche} 

Der dem Keyword „search“ folgende Slash (/) ist dabei obligatorisch. Die Suchanfrage selbst setzt sich aus mehreren Parametern zusammen. Diese werden in der üblichen Form in dem URL codiert:

?option1=valeur1&option2=valeur2&option3=valeur3 

La requête de recherche complète se présente donc sous le format suivant :

http://bennohost:21080/search/?option1=wert1&option2=wert2... 

Remarque : Pour des raisons d’impression, certaines URL s’affichent sur plusieurs lignes. Elles doivent cependant être saisies sur une seule ligne, sans espaces, etc

Voici la représentation syntaxique des requêtes de recherche. Vous trouverez plus bas des exemples concrets de requêtes de recherche.

Les requêtes de recherche dans Benno MailArchiv sont toujours rédigées en utilisant la syntaxe de requête Apache Lucene. La syntaxe Lucene complète est disponible, par exemple, dans les sources suivantes :

• http://lucene.apache.org/core/3_6_2/queryparsersyntax.html
• http://www.lucenetutorial.com/lucene-query-syntax.html

http://bennohost:21080/search/?archive=container-identifier&query=suchanfrage

Exemple utilisant cURL :

curl -u benno2:<shared secret> \
  --data archive=BennoContainer \
  --data 'query=Text:hallo' \
  --data 'filterQuery=(*)' \
  --data start=0 \
  --data limit=20 \
  -D - -k http://localhost:21080/search/

http://bennohost:21080/search/?archive=container-identifier&filterQuery=filter&query=suchanfrage

L'utilisation de filtres dans les requêtes de recherche permet un traitement plus efficace de ces dernières. L'ordre de traitement dans Lucene est le suivant :

Premièrement, la requête est exécutée, puis la liste des résultats est filtrée à l'aide de la requête de filtrage.

Hinweis: Alle (auch komplexe) Suchanfragen können als „query“ gestaltet werden. Die Filterung kann bspw. ergänzend verwendet werden, um die Menge der Suchergebnisse auf E-Mails mit bestimmten Merkmalen einzugrenzen. Bspw. werden alle Suchanfragen der Benno MailArchiv WebApp über „query“ abgebildet, während die Benutzerberechtigungen durch Filter („filterQuery“) abgebildet werden.

Une requête de recherche comprend au moins les paramètres suivants :

• archive : identifiant unique du conteneur dans lequel la recherche doit être effectuée
• requête : La requête de recherche proprement dite
• filterQuery : Critères de filtrage appliqués aux résultats de la recherche après la recherche

Outre les paramètres obligatoires mentionnés ci-dessus, les requêtes de recherche peuvent également contenir les paramètres optionnels suivants :

• start: Nummer des ersten auszugebenden Ergebnis-Elements (Standard: 1) (1..n)
• limit: Anzahl der auszugegebenen Elemente des Ergebnisses (Standard: 20)
• sort: Attribut, nach dem die Trefferliste sortiert werden soll (Standard: „sent“ (Sendedatum))
• sortAsc: Sortierung aufsteigend (Standard: false)
• full: Ausgabe aller Attribute der Maildokumente (Standard: false)

• Valeurs de résultat (codes d'erreur HTTP de l'opération de recherche) :
  • 1xx - Informations
  • 2xx - OK…
  • 3xx - Demandes
  • 4xx - Erreurs temporaires
  • 5xx - Erreurs persistantes

• Données de résultats (résultats de recherche ou listes de résultats) :
• limite : telle que déterminée par les paramètres ou les valeurs par défaut
• trouvé : Nombre d'e-mails trouvés
• premier : Position dans les résultats de recherche de la première ligne affichée (1..n, 0 si aucune ligne n'a été affichée)
• dernière : Position dans le résultat de recherche de la dernière ligne affichée (1..n, 0 si aucune ligne n'a été affichée)
• nombre : Nombre de lignes dans cette valeur de retour
• résultats : liste des résultats ; tableau d’objets JSON ayant la structure suivante :
• De : Adresse de l'expéditeur
• à : Adresses de destination
• multipart : 1 si multipart, 0 sinon
• Sujet : Sujet
• Résumé : Résumé
• envoyé : la date d'expédition
• id : identifiant unique du courriel archivé (nécessaire pour le récupérer dans les archives)

Die nachfolgenden Beispiele für Suchanfragen beginnen alle mit dem folgenden HTTP URL. Dieser URL wird in den Beispielen nicht weiter extra aufgeführt.

http://bennohost:21080/search/ 

Veuillez noter que les requêtes de recherche sont généralement sur une seule ligne, même si elles sont souvent affichées sur plusieurs lignes ci-dessous !

Wie bereits eingangs erwähnt, raten wir ausdrücklich dazu, diese Form der Autorisierung nicht in browser-basierten Web-Anwendungen einzusetzen, da das Shared Secret im Klartext in der URL enthalten ist bzw. im Browser nachgelesen werden kann!

http://benno2:shared-secret@localhost:21080/search/... 

?archive=BennoContainer&query=(Expéditeur :*hansen-und-meyer*) 

Cette requête de recherche recherche tous les courriels dans le conteneur standard2 qui proviennent d'adresses d'expéditeur contenant littéralement « hansen-und-meyer ».

?archive=BennoContainer&query=((Expéditeur :*hansen-und-meyer*)) ET (Destinataire :vertrieb@*))

Cette requête de recherche recherche tous les courriels dans le conteneur standard qui proviennent d'adresses d'expéditeur contenant littéralement « hansen-und-meyer » ET dont les adresses de destinataire contiennent littéralement « vertrieb@ ».

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*)) AND (SortableDate:[201308231020 TO 201308271605]))

Cette recherche concerne les courriels datant de la période comprise entre le 23/08/2013 à 10h20 et le 27/08/2013 à 16h05.

Anmerkung: Ein Bereich kann als [inklusiv] oder {exklusiv} formatiert definiert werden.

• SortableDate:[197001010000 TO 201512312400] - inklusiver Bereich, Ergebnisse bis zum 31.12.2015 24:00
• SortableDate:{197001010000 TO 201512312400} - exklusiver Bereich, Ergebnisse nach dem 31.12.2015 24:00

?archive=BennoContainer&filterQuery=(Destinataire :vertrieb@*)&query=(Expéditeur :*hansen-und-meyer*)

Cette requête de recherche porte également sur tous les courriels dont l'adresse de l'expéditeur contient littéralement « hansen-und-meyer ». Les résultats sont ensuite filtrés. Tous les courriels dont l'adresse du destinataire ne contient pas « vertrieb@ » sont exclus.

Comme nous l'avons vu, les deux voies mènent au même résultat.

?archive=BennoContainer&query=((Expéditeur :*hansen-und-meyer*)) (Destinataire :vertrieb@*))

Cette requête de recherche recherche tous les courriels dans le conteneur standard qui proviennent d'adresses d'expéditeur contenant littéralement « hansen-und-meyer » OU dont les adresses de destinataire contiennent littéralement « vertrieb@ ».

Outre les critères de recherche relatifs à l'expéditeur et au destinataire, d'autres critères sont disponibles. La liste complète de ces critères figure en annexe de cette documentation (voir la section « Critères de recherche dans les requêtes »).

Hinweis: Alle Suchkriterien können in Suchanfragen in beliebiger Form (UND, ODER) und in beliebiger Reihenfolge miteinander kombiniert werden.

Der API-Call zum Zugriff auf eine archivierte E-Mail dient dazu, eine E-Mail (incl. etwaiger Attachements) aus dem Archiv zu holen. Da jede E-Mail im Archiv eindeutig identifiziert ist, erfolgt der Zugriff über diesen eindeutigen Identifyer.

Remarque : Pour des raisons d’impression, certaines URL s’affichent sur plusieurs lignes. Elles doivent cependant être saisies sur une seule ligne, sans espaces, etc

Voici la représentation syntaxique d'une requête de recherche. Vous trouverez plus bas des exemples concrets de récupération d'e-mails.

Der Aufruf erfolgt analog der zu Suchanfragen als HTTP URL. Die Syntax ist dabei grundsätzlich:

http://bennohost:21080/mail/?archive=identifiant-container&id=id 

La récupération d'un courriel se compose des deux paramètres suivants :

• archive : identifiant unique du conteneur à partir duquel le courriel doit être lu
• id : L’identifiant unique de l’e-mail (ID), y compris le nom de la boîte au format conteneur. <box»<mailid>

Die aus dem Archiv gelesene E-Mail wird standardmäßig als JSON Objekt an das aufrufende Programm zurückgegeben. Mittels der Option format kann die Rückgabe der E-Mail im „raw“ Format, also RFC 822 bzw. RFC 2822 (Plaintext) erzwungen werden.

• format: „raw“, wenn die Mail im RFC-822 Format zurückgegeben werden soll.

• 1xx - Informations
• 2xx - OK…
• 3xx - Demandes
• 4xx - Erreurs temporaires
• 5xx - Erreurs persistantes

Une pièce jointe peut être référencée par son nom de fichier ou par son identifiant.

http://bennohost:21080/attachment/?archive=identifiant-container&id=id&attachment=Nom_de_fichier

http://bennohost:21080/attachment/?archive=container-identifier&id=id&attachmentId=0

• archive : identifiant unique du conteneur à partir duquel le courriel doit être lu
• id : L’identifiant unique de l’e-mail (ID), y compris le nom de la boîte au format conteneur. <box»<mailid>
• Pièce jointe : Nom du fichier joint
• attachmentId : identifiant de la pièce jointe tel que spécifié dans la liste des pièces jointes.

http://localhost:21080/mail/?archive=BennoContainer&id=2012:1C6626F53B0B...67ADA0 FB4E

Dieser Abruf liest die E-Mail mit der eindeutigen ID „1C6626F53B0B...67ADA0 FB4E“ aus dem Archiv und gibt sie an das aufrufende Programm zurück. Die E-Mail wird dabei aus der Box „2012“ des Containers „BennoContainer“ gelesen.

Il est possible de rechercher des adresses électroniques en utilisant tout le contenu indexé. Les critères de recherche peuvent être saisis individuellement ou combinés à l'aide des opérateurs logiques « ET » et « OU ». Pour plus de détails sur la syntaxe, veuillez consulter les informations ci-dessus et la documentation Apache Lucene correspondante (URL ci-dessus).

Folgende Suchkriterien stehen über die API für Suchanfragen zur Verfügung:

• Date : Date de l'e-mail
• De : Adresse e-mail de l'expéditeur
• Destinataire : Adresses des destinataires (y compris À, Cc et Cci)
• Domaine du destinataire : Domaine du destinataire
• Expéditeur : Adresse e-mail de l'expéditeur
• SenderDomain : Domaine de l'expéditeur
• Taille : Taille du courriel
• Objet : Objet de l'e-mail
• À : Adresses des destinataires
• pièce jointe : Courriel avec pièce jointe
• id : Identifiant unique de l’e-mail dans l’archive
• Cc : Adresses des destinataires
• Texte : Rechercher des mots dans le texte du courriel (y compris le texte des pièces jointes)
• EN-TÊTE-XYZ : L’en-tête de courriel « XYZ » contient une valeur spécifique (le nom de l’en-tête doit être écrit en LETTRES MAJUSCULES)

La requête de recherche ci-dessous, par exemple, donne un ensemble de résultats de 2 adresses e-mail :

http://bennohost:21080/search/?archive=BennoContainer&query=(Sender:*hansen-und-meyer*)

Le résultat de la recherche (2 résultats) est renvoyé sous forme d'objets JSON et contient, par exemple, le contenu suivant :

{ "licenseValid":true, "limit":2, "results" { "id":"2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00", "SubjectRe: Demande de renseignements concernant un partenariat", "Date201206191122", "hasAttachment1", "To":["W. Robert"<w.robert@robert-druck.de> ], "Bcc":[], "Cc":[], "De":"info@hansen-und-meyer.de" }, { "id":"2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00", "Subject":"Re: Demande concernant un partenariat", "Date":"201206191122", "hasAttachment":"1", "To":["w.robert@robert-druck.de"], "Bcc":[], "Cc":[], "De":"info@hansen-und-meyer.de" } ], "last":1, "count":2, "overall":25, "first":0, "found":14 }

La représentation de ce résultat de recherche dans un langage de programmation tel que PHP ou Perl pourrait ressembler à ceci :

$VAR1 = { 'first' => 0, 'count' => 2, 'last' => 1, 'found' => 14, 'overall' => 25, 'licenseValid' => 1, 'limit' => 2, 'results' => [ { 'Cc' => [], 'Subject' => "Re: Request regarding\x{c3}\x{bc}partnership", 'Date' => '201206191122', 'Bcc' => [], 'hasAttachment' => '1', 'id' => '2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00', 'To' => ['"W. Robert"<w.robert@robert-druck.de> '], 'From' => 'info@hansen-und-meyer.de' }, { 'Cc' => [], 'Subject' => "Re: Demande concernant un partenariat", 'Date' => '201206191122', 'Bcc' => [], 'hasAttachment' => '1', 'id' => '2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00', 'To' => ['w.robert@robert-druck.de'], 'From' => 'info@hansen-und-meyer.de' } ] }

Voici un exemple de courriel extrait des archives :

http://bennohost:21080/mail/?archive=BennoContainer&id=2012:1C6626F5E02E1B3B0B74D...A83C130162B077AD6AB00

Le résultat (l'e-mail) est renvoyé par défaut sous forme d'objets JSON et contient, par exemple, les éléments suivants :

{ 'body' => [ { 'content-type' => 'text/plain', 'data' => "Sehr geehrter Herr Robert, wir danken f\x{c3}\x{bc}r das Interesse an unseren Produkten, das Sie mit Ihrer E-Mail gezeigt haben. Wir haben dieser E-mail ein Angebot hinzugef\x{c3}\x{bc}gt und hoffen, dass wir baldig diesbez\x{c3}\x{bc}glich von Ihnen h\x{c3}\x{b6}ren werden. Unsere Gesch\x{c3}\x{a4}ftsbedingungen entnehmen Sie bitte den beigef\x{c3}\x{bc}gten PDF-Dokument. Bei weiteren Fragen stehen wir Ihnen selbstverst\x{c3}\x{a4}ndlich auch telefonisch zur Seite. Sie k\x{c3}\x{b6}nnen uns unter der Rufnummer 0541/123456-1, von Mo. bis Fr. zwischen 09:00 und 17:00 Uhr, erreichen. Mit freundlichen Gr\x{c3}\x{bc}\x{c3}\x{9f}en, Papierfabrik Hansen & Meyer GmbH i. A. Sabine Petersen Papierfabrik Hansen & Meyer GmbH | Seelenhof 5 | 49100 Sch\x{c3}\x{b6}nlingen | Tel.: 0541/123456-1 | info\@hansen-und-meyer.de " } ], 'attachments' => [ { 'content-type' => 'application/pdf', 'name' => 'preisangebot.pdf', 'attachmentId' => "0", 'size' => 44513 }, { 'content-type' => 'application/pdf', 'name' => 'agb.pdf', 'attachmentId' => "1", 'size' => 63258 } ], 'header' => { 'Cc' => [], 'User-Agent' => 'Mozilla-Thunderbird 2.0.0.22 (X11/20090706)', 'Subject' => "Re: Anfrage bez\x{c3}\x{bc}glich Partnerschaft", 'MIME-Version' => '1.0', 'In-Reply-To' => '<4AC1E7D2.6070302@web.de>', 'Date' => 'Tue, 19 Jun 2012 13:22:38 +0200', 'Bcc' => [], 'Size' => 109490, 'References' => '<4AC1E7D2.6070302@web.de>', 'Message-ID' => '<4AC1EDFE.8070406@web.de>', 'Content-Type' => 'multipart/mixed; boundary="------------070101070508030007040901"', 'To' => [ 'w.robert@robert-druck.de' ], 'From' => 'info@hansen-und-meyer.de' 'X-Benno-HashCheckPassed' => 1, 'X-Benno-DateTS' => 1340104958 }, };

• 400 - Erreur de requête
• 404 - Conteneur introuvable
• 503 - Erreur interne
• 901 - Index non initialisé