MailArchiva REST Web Services API 

 

The MailArchiva server offers a REST web services API. The API enables programmatic access to many of the product's features; including: conducting searches, retrieving and inserting data, traversing folder structures, sending data, managing tags and legal holds.

 

How to generate an Api key

 

Login to the MailArchiva web console as admin. From Configuration->Logins, check Allow Api access, and click the Re-generate button to generate an API key. Take note of the curl command to perform a basic search via the REST API.

 

 

Swagger Api documentation

 

Once the server is installed, visit https://localhost:8090/api-docs for further instructions on how to use the API. Alternatively, visit  https://demo.mailarchiva.com/api-docs to see the MailArchiva Demo Api docs.

 

Security considerations


WARNING! To protect against network sniffing, ensure that the console is secured by HTTPS. 


Dictionary attack


When authenticating, if three consecutive password attempts are supplied, the server will reject all authentication attempts for the same user for a long time period.

Furthermore, on each wrong attempt, the server will pause for at least twenty seconds.


Search query syntax


Search queries are specified in the same syntax as accepted by the MailArchiva search interface. For example, the query "subject:membership" would return all emails with the value "membership" in the subject field. For a complete description of fields that can be used in a search query, refer to Search Fields. The query syntax is in line with the Lucene Query Parser Syntax. 
 

XPath query syntax


Search queries filter out the desired set of emails (or blobs) to be included in the search result. XPath queries, however, may be used to traverse actual blob objects and inspect their properties. Internally, MailArchiva uses Commons JXPath to provide the means to traverse the characteristics of a blob.

 

Accepted date formats

 

The REST API parses dates (such as before and after params in search query) in accordance with RFC 2616 Section 3.3.1. The date should be in one of the following formats (the first one being the most relevant).

 

      Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
      Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
      Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format

 

Generic blob properties

 

All blob types share the properties listed below.

 

field type description
blobid blobid ID of blob. Blobid consists of (volume,id,verid)
body list<string> list of input stream text
download stream download data
export stream export data
send stream send data
archive stream archive data
view stream view data
print stream print data
filename string name of file
mimetype string mime type of blob
size long size of message (in bytes)

 

BlobID Properties

 

The BlobID is used for looking up blobs in the store.
 

field type description
volume string unique id of the volume (optional)
id string unique id of the blob (required)
verid stream unique id of the blob version (optional)

 

Email Properties (In Addition To Above)

In addition to the common properties above, the email blob type offers the following additional properties:

 

Field Typ Description
antivirus string whether or not message contains a virus
archivedate date archive date of message
attach boolean whether or not has an attachment
attachmentlist list<blob> list of actual attachment objects
attachments list<string> list of attachment text (used for indexing)
attachname list<string> all attachment file names
attachsize list<long> size of each attachment (in bytes)
bcc string blind carbon copy recipients
blobid blobID ID of blob. BlobID consists of (volume,id,verid,appid)
body list<string> body of a message
cc string carbon copy recipients
flag string any flags associated with message
from string from email address
journalbcc string journal BCC recipients
journalcc string journal CC recipients
journalrecipients string all journal recipients
journalsender string all journal sender recipients
journalto string journal TO recipients
mailfrom string mail from smtp header value
memberof string ad group this message is part of
messageid string id of message (not to be confused with MailArchiva message id)
parts list<blob> list of body parts
priority string priority of message
rcptto string rcptto smtp header value
receiveddate string date when message was received
recipients string all recpieints
sensitivity string sentivity of message
sentdate date sent date of message
subject string subject of message
thread boolean whether the message is part of a thread or not
to string to email addresses

 

Further addressable blob fields are defined in the Blob Field Definition.

 

Generating a client stub using swagger

 

For convenience, each newly minted MailArchiva distribution includes a Swagger definition for MailArchiva's REST API. The Swagger definition specified in the swagger.json file, may be used to generate a binding in your programming language of choice and is dynamically updated as part of MailArchiva's build process. For example, to generate a Python client stub, upload the JSON file into the Swagger Editor, then click Generate Client and choose Python as the language.

 

/opt/mailarchiva/server/ws/swagger.json (Linux)

C:\Program Data\MaiLArchiva\server\ws/swagger.json (Windows)

 

Swagger.json Upload Pre-requisite: To avoid a validation error, before uploading the swagger.json file into the Swagger Editor, open the file using a text editor, and specify the API host name in the host entry.

"host""host": : "mailarchiva.company.local""mailarchiva.company.local",,

 

© 2005 - 2024 ProProfs

Found this information useful? Visit mailarchiva.com to learn more about MailArchiva.

-