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://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:
Suchanfragen können neben den o.g. Pflichtparametern zusätzlich folgende optionale Parameter enthalten:
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:
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.
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.
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
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:
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:
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
},
};