Vaultastic eDiscovery API to access Active Store data

Overview

The Vaultastic eDiscovery API enables developers to programmatically search and retrieve email data stored in the Vaultastic Active Store. The API is designed for integrating Vaultastic with third-party applications, eDiscovery workflows, compliance solutions, and custom business processes.

Using the API, applications can:

Search archived emails using a variety of search criteria.
Retrieve and export the complete contents of selected emails.

The Vaultastic eDiscovery API is REST-based and currently provides the following endpoints:

Endpoint	Description
Search API	Searches the Vaultastic Active Store and returns a list of emails that match the specified search criteria.
Export API	Retrieves and exports the complete content of a selected email returned by the Search API.

Obtaining API Access

To use the Vaultastic eDiscovery API, you must obtain an API access key.

To request an API key, raise a support ticket with Mithi Customer Care and provide the Vault ID for which API access is required.

Note
API access can only be enabled for Vault IDs that have Self Service or Full Access permissions to data stored in the Vaultastic Active Store.

Rate Limits

Each API access key is subject to the following default rate limits. These limits are shared across both the Search API and Export API.

Limit	Default Value
Requests per second	100 API calls
Requests per month	5,000 API calls
Number of keys	A single active key at a time

If your application requires higher throughput, please contact Mithi Customer Care to discuss increased rate limits.

API Key Security

Your API access key provides access to archived data and should be treated as a sensitive credential.

Vaultastic follows these practices:

API access keys are delivered securely through approved communication channels.
Each API key is associated with a specific Vault ID and its corresponding access permissions.

Customers are responsible for protecting their API credentials. We recommend the following best practices:

Store API keys securely using a secrets management solution or encrypted configuration store.
Never embed API keys directly in application source code.
Do not expose API keys in client-side applications or public repositories.
Rotate API keys periodically and immediately if you suspect they have been compromised.

Next Steps

After obtaining an API access key, you can:

Authenticate your application using the provided API key.
Use the Search API to locate archived emails.
Use the Export API to retrieve the full content of selected emails.
Integrate the API into your eDiscovery, compliance, or archival workflows.

Using the Search API

Endpoint

POST https://ediscovery.vaultastic.com/v1/search

Headers

Header	Description
`CallerId`	The vault id of the user making the request (e.g. `bhushan.wawre@archive.mithi.com`)

Request Body

Send a JSON object with the search parameters. An empty body ({}) returns all archived emails accessible to the caller.

All fields are optional. However, date-from and date-to must always be used together — if one is provided, the other must also be provided.

Date fields use the format YYYY-MM-DD (e.g. 2026-06-01).

Parameter	Type	Description
`from`	string	Filter by sender email address.
`to`	string	Filter by recipient email address.
`cc`	string	Filter by CC email address.
`bcc`	string	Filter by BCC email address.
`subject`	string	Filter by email subject (supports partial match).
`body`	string	Filter by text in the email body.
`attachment-text`	string	Filter by text found within attachments.
`attachment-filename`	string	Filter by attachment filename.
`date`	string	Filter emails on a specific date. Format: `YYYY-MM-DD`.
`date-from`	string	Start of a date range (inclusive). Format: `YYYY-MM-DD`. Must be used together with `date-to`.
`date-to`	string	End of a date range (inclusive). Format: `YYYY-MM-DD`. Must be used together with `date-from`.
`start`	integer	Zero-based index of the first result to return. For page N (1-based) with page size P, set `start` to `(N-1) \* P`.
`rows`	integer	Number of results to return per page (i.e. page size).

Pagination

Use the start and rows fields together to page through results. rows sets the page size and start sets the offset of the first result on that page.

With a page size of 50:

Page	`start`	`rows`
1	0	50
2	50	50
3	100	50
N	`(N-1) \* 50`	50

Use response.numFound from the response to determine the total number of results and calculate how many pages exist.

Example — fetch page 2:

JSON

{  "start": 50,  "rows": 50}

Response

Returns a JSON object with the following structure:

JSON

Plain Text

{

"responseHeader": {

"status": 0,

"QTime": 0,

"params": {}

"response": {

"numFound": 1406,

"start": 0,

"numFoundExact": true,

"docs": [

{

"id": "uuid",

"path": "s3://...",

"vault": [

"user@domain.com"

"from": [

"sender <sender@domain.com>"

"to": [

"recipient <recipient@domain.com>"

"cc": [],

"bcc": [],

"date": "2022-11-01T07:29:48Z",

"domain": "archive.mithi.com",

"subject": "Email subject",

"message-id": "<message-id>",

"msgsize": 311971,

"attachment-info": ""

}

]

}

Field	Description
`responseHeader.status`	`0` indicates success
`responseHeader.QTime`	Query execution time in milliseconds
`response.numFound`	Total number of matching emails
`response.start`	Offset of the first result returned
`response.docs`	Array of matching email documents
`docs[].id`	Unique identifier (UUID) of the archived email
`docs[].path`	S3 path to the raw `.eml` file
`docs[].vault`	List of vault addresses the email is associated with
`docs[].from`	Sender address(es)
`docs[].to`	Recipient address(es)
docs[ ].cc	cc recipient address(es)
docs[ ] .bcc	bcc recipient address(es)
docs[ ].message-id	mails message id
`docs[].date`	Email date in ISO 8601 format
`docs[].domain`	Archive domain
`docs[].subject`	Email subject line
`docs[].msgsize`	Size of the email in bytes
`docs[].attachment-info`	Attachment metadata, if any

Error Cases

HTTP-level errors

HTTP Status	Meaning	Likely Cause
`400 Bad Request`	Malformed request	Invalid JSON body or unsupported Solr query syntax in `q` or `fq`
400 Bad Request	Authentication failure	Missing or invalid `CallerId` header
`403 Forbidden`	Access denied	The `CallerId` user does not have permission to search the requested domain or vault or x-api-key missing/invalid
403 Forbidden	Endpoint not found	Incorrect URL path
`500 Internal Server Error`	Server-side failure	Unexpected error on the Vaultastic backend

Application-level errors (within a 200 response)

The API may return HTTP 200 but indicate a failure via responseHeader.status in the response body:

`responseHeader.status`	Meaning
`0`	Success — query executed without errors
Non-zero	Solr-level error — check `responseHeader.error` for details

Example error response body:

JSON

{
  "responseHeader": {
    "status": 400,
    "QTime": 2
  },
  "error": {
    "metadata": [
      "error-class",
      "org.apache.solr.common.SolrException",
      "root-error-class",
      "org.apache.solr.common.SolrException"
    ],
    "msg": "undefined field path",
    "code": 400
  }
}

Common error scenarios

Scenario	Symptom	Resolution
Missing `CallerId` header	`400` or empty results	Add the `CallerId` header with a valid archive email address
`numFound: 0` with no error	Empty `docs` array	No emails match the query — refine `q` or `fq` parameters
Pagination out of range	Empty `docs` array	`start` value exceeds `numFound`; reduce `start` or check total count first

Using the Export API

Retrieves the full content of a single archived email by its S3 storage path.

The path value is typically obtained from the docs[].path field in the response of the POST /v1/search endpoint.

Endpoint

POST https://ediscovery.vaultastic.com/v1/export

Headers

Header	Description
`CallerId`	The vault id of the user making the request (e.g. `bhushan.wawre@archive.mithi.com`)

Request Body

Send a JSON object with the S3 path of the email to export:

Parameter Type Required Description

Parameter	Type	Required	Description
`path`	string	Yes	The S3 path to the `.eml` file, as returned in `docs[].path` from the search endpoint

path

string

Yes

The S3 path to the .eml file, as returned in docs[].path from the search endpoint

Example:

JSON

{
  "path": "s3://ind1-mithi-vv4-dc1-mailstore-s3/archive.mithi.com/data/mail/47e9a06d-74a5-4356-9483-df9fb89efe5f.eml"
}

Response

Returns a JSON object with the fully parsed email content, including headers, body parts, and attachments.

JSON

{
  "subject": "Re: [Ticket#2022090710000045] ...",
  "headers": {
    "from": ["\"Sender Name\" <sender@domain.com>"],
    "to": ["\"Recipient Name\" <recipient@domain.com>"],
    "cc": ["cc1@domain.com, cc2@domain.com"],
    "bcc": [],
    "reply-to": [],
    "date": "2022-11-01T07:29:48.000Z",
    "message-id": "<unique-message-id@domain.com>",
    "in-reply-to": "<parent-message-id@domain.com>",
    "references": "",
    "x-vaultastic-header": "<base64-encoded-metadata>",
    "x-vault": "user@archive.domain.com",
    "x-vaultastic-primary-domain": "archive.domain.com",
    "received": ["...SMTP trace entries..."]
  },
  "body": [
    {
      "type": "text/plain",
      "content": "Plain text body of the email"
    },
    {
      "type": "text/html",
      "content": "<html>HTML body of the email</html>"
    }
  ],
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 12345,
      "content": "<base64-encoded-content>"
    }
  ]
}

Response Fields

Field	Description
`subject`	The email subject line
`headers`	Object containing all email headers
`headers.from`	Sender address(es)
`headers.to`	Primary recipient address(es)
`headers.cc`	CC recipient address(es)
`headers.bcc`	BCC recipient address(es)
`headers.reply-to`	Reply-to address(es), if set
`headers.date`	Email send date in ISO 8601 format
`headers.message-id`	Unique message identifier
`headers.in-reply-to`	Message ID of the email being replied to
`headers.x-vaultastic-header`	Base64-encoded Vaultastic metadata (sender, server IP, received time, UUID, mail router type, recipient)
`headers.x-vault`	The vault address the email is stored under
`headers.x-vaultastic-primary-domain`	The primary archive domain
`headers.received`	SMTP relay trace entries
`body`	Array of body parts (plain text and/or HTML)
`body[].type`	MIME type of the body part (e.g. `text/plain`, `text/html`)
`body[].content`	Content of the body part
`attachments`	Array of attachment objects (empty if none)
`attachments[].filename`	Attachment file name
`attachments[].contentType`	MIME type of the attachment
`attachments[].size`	Size of the attachment in bytes
`attachments[].content`	Base64-encoded attachment content

Error Cases

HTTP-level errors

HTTP Status	Meaning	Likely Cause
`400 Bad Request`	Malformed request	Missing or invalid `path` field in the request body, or malformed JSON
`401 Unauthorized`	Authentication failure	Missing or invalid `CallerId` header
`403 Forbidden`	Access denied	The `CallerId` user does not have permission to access the email at the given path
`404 Not Found`	Email not found	The S3 path does not exist or the email has been deleted
`500 Internal Server Error`	Server-side failure	Unexpected error on the Vaultastic backend (e.g. S3 read failure)

Common error scenarios

Scenario	Symptom	Resolution
Missing `path` field	`502 Bad Gateway`	Ensure the request body contains a `path` key with a valid S3 URI
Stale or incorrect S3 path	`404 Not Found`	Re-run the search to get a fresh `path` value from `docs[].path`
Missing `CallerId` header	`400 Bad Request`	Add the `CallerId` header with a valid archive email address
`CallerId` lacks access to the vault	`403 Forbidden`	Use a `CallerId` that has read access to the domain or vault the email belongs to
Path from a different environment	`404 Not Found` or `403 Forbidden`	Ensure the `path` was obtained from the same environment (staging vs. live) you are calling
Missing Api Key	`403 Forbidden`	Missing or invalid x-api-key

Vaultastic eDiscovery API to access Active Store data

Overview

Obtaining API Access

Rate Limits

API Key Security

Next Steps

Using the Search API

Endpoint

Headers

Request Body

Pagination

Response

Error Cases

HTTP-level errors

Application-level errors (within a 200 response)

Common error scenarios

Using the Export API

Endpoint

Headers

Request Body

Response

Response Fields

Error Cases

HTTP-level errors

Common error scenarios

Related Articles