Das REST API bietet ausschließlich eine generelle Authentisierung ohne Zugriffssteuerung für einzelne Benutzer. Auf das API kann über das Rest Interface zugegriffen werden. Es dient ausschließlich dazu, Requests der REST Frontends zu verarbeiten.

Suchanfragen dienen zur Suche nach archivierten E-Mails. Da alle E-Mails incl. ihrer Attachements volltext-indexiert vorliegen, können E-Mails anhand jeden beliebigen Inhalts bzw. anhand jedes beliebigen Merkmals (und selbstverständlich auch beliebiger Kombinationen von Merkmalen) gefunden werden.

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

http://bennohost:21080/search/{suchanfrage} 

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=wert1&option2=wert2&option3=wert3 

Die vollständige Suchanfrage hat damit folgendes Format:

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

Hinweis: Die URLs werden aus drucktechnischen Gründen teilweise mehrzeilig dargestellt. Sie sind jedoch ohne Leerzeichen usw. in einer Zeile anzugeben!

Hier zunächst die syntaktische Darstellung von Suchanfragen. Weiter unten sind konkrete Beispiele für Suchanfragen abgebildet.

Suchanfragen werden in Benno MailArchiv grundsätzlich in der Query-Syntax von Apache Lucene verfasst. Die vollständige Syntax von Lucene kann bspw. in den nachstehenden Quellen nachgelesen werden:

• 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

Beispiel mit 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

Die Verwendung von Filtern in Suchanfragen kann zu effizienterem Verarbeiten der Abfragen führen. Die Verarbeitungsreihenfolge in Lucene ist dabei:

zunächst Ausführung der „query“, danach Filterung der Ergebnisliste mit der „filterQuery“.

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.

Eine Suchanfrage setzt sich aus mindestens folgenden Parametern zusammen:

• archive: eindeutiger Identifier des Containers, in dem die Suche erfolgen soll
• query: Die eigentliche Suchanfrage
• filterQuery: Filterkriterien, die nach der Suche auf das Suchergebnis angewendet werden

Suchanfragen können neben den o.g. Pflichtparametern zusätzlich folgende optionale Parameter enthalten:

• 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)

• Resultatwerte (HTTP-Fehlercodes der Suchoperation):
  • 1xx - Information
  • 2xx - OK …
  • 3xx - Aufforderungen
  • 4xx - Temporäre Fehler
  • 5xx - Dauerhafte Fehler

• Resultatdaten (Suchergebnisse bzw. Trefferlisten):
• limit: wie aus den Parametern, oder die Defaultwerte
• found: Anzahl der gefundenen E-Mails
• first: Stelle im Suchergebnis der ersten ausgegebenen Zeile (1..n, 0 falls keine Zeile ausgegeben wurde)
• last: Stelle im Suchergebnis der letzten ausgegebenen Zeile (1..n, 0 falls keine Zeile ausgegeben wurde)
• count: Anzahl der Zeilen in dieser Rückgabe
• results: Trefferliste; Array mit JSON Objekten mit dem folgenden Aufbau:
• from: Absenderadresse
• to: Zieladressen
• multipart: 1 wenn Mehrteilig, 0 wenn nicht
• subject: Betreff
• summary: Zusammenfassung
• sent: das Absendedatum
• id: eindeutige ID der archivierten E-Mail (notwendig, um diese aus dem Archiv abrufen zu können)

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/ 

Weiterhin ist zu beachten, dass die Suchanfragen grundsätzlich einzeilig sind, auch wenn sie nachstehend oft mehrzeilig dargestellt werden!

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=(Sender:*hansen-und-meyer*) 

In dieser Suchanfrage werden alle E-Mails im Standard-Container2 gesucht, die von Absenderadressen stammen, in denen das Literal „hansen-und-meyer“ vorkommt.

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*)) AND (Recipient:vertrieb@*))

In dieser Suchanfrage werden alle E-Mails im Standard-Container gesucht, die von Absenderadressen stammen, in denen das Literal „hansen-und-meyer“ vorkommt UND deren Empfängeradressen das Literal „vertrieb@“ enthalten.

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

Hier werden die E-Mails im Zeitraum zwischen 23.08.2013 10:20 und dem 27.08.2013 um 16:05 gesucht.

?archive=BennoContainer&filterQuery=(Recipient:vertrieb@*)&query=(Sender:*hansen-und-meyer*)

Bei dieser Suchanfrage werden ebenfalls alle Mails gesucht, deren Absenderadresse das Literal „hansen-und-meyer“ enthält. Anschließend werden die Ergebnisse gefiltert. Es werden alle E-Mails ausgefiltert, deren Empfängeradressen nicht „vertrieb@“ enthalten.

Wie gesehen, führen beide Wege zum gleichen Ergebnis.

?archive=BennoContainer&query=((Sender:*hansen-und-meyer*)) (Recipient:vertrieb@*))

In dieser Suchanfrage werden alle E-Mails im Standard-Container gesucht, die von Absenderadressen stammen, in denen das Literal „hansen-und-meyer“ vorkommt ODER deren Empfängeradressen das Literal „vertrieb@“ enthalten.

Neben den Suchkriterien für Sender bzw. Recipient stehen weitere Suchkriterien zur Verfügung. Eine Liste aller Suchkriterien befindet sich im Anhang dieser Dokumentation (siehe Abschnitt „Suchkriterien in Suchabfragen“).

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.

Hinweis: Die URLs werden aus drucktechnischen Gründen teilweise mehrzeilig dargestellt. Sie sind jedoch ohne Leerzeichen usw. in einer Zeile anzugeben!

Hier zunächst die syntaktische Darstellung eines Abrufs. Weiter unten sind konkrete Beispiele für das Abrufen von E-Mails abgebildet.

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

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

Der Abruf einer E-Mail setzt sich aus den beiden folgenden Parametern zusammen:

• archive: eindeutiger Identifier des Containers, aus dem die E-Mail gelesen werden soll
• id: Der eindeutige Identifyer der E-Mail (ID) incl. der Bezeichnung der Box im Container - Format <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 - E-Mail im RFC-822 Format anfordern
• skipUTF8Recode=true - E-Mail im Orginal zurück geben
• header=true - Secret Header zurück geben

Achtung! Um eine E-Mail aus dem Repo zum Re-Indexieren ist es erforderlich, die E-Mail ohne Anpassung des Encodings zu laden. Daher ist hier der Parameter skipUTF8Recode=true zwingend erforderlich.

• 1xx - Information
• 2xx - OK …
• 3xx - Aufforderungen
• 4xx - Temporäre Fehler
• 5xx - Dauerhafte Fehler

Ein Attachment kann über den Dateinamen oder über die Attachment-Id referenziert werden.

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

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

• archive: eindeutiger Identifier des Containers, aus dem die E-Mail gelesen werden soll
• id: Der eindeutige Identifyer der E-Mail (ID) incl. der Bezeichnung der Box im Container - Format <box»<mailid>
• attachment: Dateiname des Attachments
• attachmentId: Id des Attachments wie in der Liste der Attachments angegeben.

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.

E-Mails können anhand aller indexierten Inhalte gesucht werden. Die Suchkriterien können einzeln oder mit den logischen Operatoren „UND“ bzw. „ODER“ kombiniert werden. Details zur Syntax siehe oben und in der einschlägigen Dokumentation zu Apache Lucene im Internet (URLs siehe oben).

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

• Date: Datum der E-Mail
• From: Absenderadresse der E-Mail
• Recipient: Empfängeradressen (beinhaltet To, Cc und Bcc)
• RecipientDomain: Domäne des Empfängers
• Sender: Absenderadresse der E-Mail
• SenderDomain: Domäne des Absenders
• Size: Größe der E-Mail
• Subject: Betreffzeile der E-Mail
• To: To-Empfängeradressen
• hasAttachment: E-Mail mit Attachement
• id: Eindeutige ID der E-Mail im Archiv
• Cc: Cc-Empfängeradressen
• Text: Suche nach Wörtern im Text der E-Mail (incl. Text aus den Attachements)
• HEADER-XYZ: Mailheader „XYZ“ enthält einen bestimmten Wert (der Name des Header muss in GROßBUCHSTABEN geschrieben werden)

Die nachstehend aufgeführte Suchanfrage ergibt bspw. eine Ergebnismenge von 2 gefundenen E-Mails:

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

Das Suchergebnis (2 Treffer) wird in Form von JSON Objekten zurückgegeben und hat bspw. folgenden Inhalt:

{ 
  "licenseValid":true, 
  "limit":2, 
  "results" 
    { 
      "id":"2012:748B034C4AF3004231D24B9DE2515822AB16485914AB3AE055C40DA336F4272F00", 
      "Subject":"Re: Anfrage bezüglich Partnerschaft", 
      "Date":"201206191122", 
      "hasAttachment":"1", 
      "To":["W. Robert" <w.robert@robert-druck.de>], 
      "Bcc":[], 
      "Cc":[], 
      "From":"info@hansen-und-meyer.de" 
    }, 
    { 
      "id":"2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00", 
      "Subject":"Re: Anfrage bezüglich Partnerschaft", 
      "Date":"201206191122", 
      "hasAttachment":"1", 
      "To":["w.robert@robert-druck.de"], 
      "Bcc":[], 
      "Cc":[], 
      "From":"info@hansen-und-meyer.de" 
    } 
  ], 
  "last":1, 
  "count":2, 
  "overall":25, 
  "first":0, 
  "found":14 
}

Bei einer Suche wird ausschließlich auf den Index von Benno MailArchiv zugegriffen. Alle hier aufgeführten Werte entsprechen direkt dem Inhalt des Indexes, während eine E-Mail bei der Anzeige aus dem Repo gelesen und für die Anzeige gesondert geparst wird.

Beim Indexieren wird der Zeitstempel aus dem Date-Header in die Zeitzone UTC konvertiert und in das entsprechende Index-Feld geschrieben. Bei Anzeige einer E-Mail wird dieser Wert in die lokale Zeitzone konvertiert.

Beim direkten Zugriff auf das REST-API muss daher darauf geachtet werden, den Inhalt von „Date“ in die jeweils lokale Zeitzone zu konvertieren.

Die Repräsentation dieses Suchergebnisses in einer Programmiersprache wie bspw. PHP oder Perl könnte bspw. so aussehen:

$VAR1 = { 
  'first' => 0, 
  'count' => 2, 
  'last' => 1, 
  'found' => 14, 
  'overall' => 25, 
  'licenseValid' => 1, 
  'limit' => 2, 
  'results' => [ 
                 {       
                   'Cc' => [], 
                   'Subject' => "Re: Anfrage bez\x{c3}\x{bc}glich Partnerschaft", 
                   '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: Anfrage bez\x{c3}\x{bc}glich Partnerschaft", 
                   'Date' => '201206191122', 
                   'Bcc' => [], 
                   'hasAttachment' => '1', 
                   'id' => '2012:1C6626F5E02E1B3B0B74DE794BC67408A64484C8B8B98A83C130162B077AD6AB00', 
                   'To' => ['w.robert@robert-druck.de'],      
                   'From' => 'info@hansen-und-meyer.de' 
                 }       
               ]       
}

Nachstehend ein Abruf einer E-Mail aus dem Archiv:

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

Das Ergebnis (die E-Mail) wird standardmäßig in Form von JSON Objekten zurückgegeben und hat bspw. folgenden Inhalt:

{ 
          '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' => true,
                        'X-Benno-DateTS' => 1340104958
                      },
        };

• 400 - Fehler beim Request
• 404 - Container nicht gefunden
• 503 - Interner Fehler
• 901 - Index nicht initialisiert