As an Account Admin, you can search your organization's archived email from your own scripts and tools with the Jatheon Cloud REST API. The API lets you run a Simple Search and open a single email, so you can answer questions like "how many emails did one person send another this week" without opening the app.

Please note that the API is read-only and search-only. Advanced Search, social media and file search, cases, exports and downloads aren't available through the API. Use the Jatheon Cloud app for those.

Get API access

API access isn't turned on by default. To request it:

1. Contact Jatheon Support and ask for REST API access for your organization.
2. Jatheon Support sets up an API client for your account and a dedicated API user with the API role.
3. You'll get a client ID and a client secret through a secure, one-time link.

Your organization can have one API user. The API role lets it run simple searches, view everyone's email, view hidden recipients and save searches. Only Jatheon Support can assign this role, and a custom role with the same permissions won't work.

Please note that the API doesn't accept your Jatheon Cloud username and password. Always use the client ID and client secret. Keep the secret safe, and if it's ever exposed, ask Jatheon Support to replace it.

Get an access token

Send a POST request to the token endpoint, with your client ID and client secret as Basic authentication:

curl -X POST https://cloud.jatheon.com/api/clients/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

The response includes:

• access_token — the token you send with every API request
• expires_in — how long the token is valid, in seconds (2 hours)
• refresh_token — a token you can use to get a new access token for up to 7 days

To get a new access token, request a new one the same way, or send grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN to the same endpoint with the same Basic authentication.

Add the access token to every API request as a header: Authorization: Bearer YOUR_ACCESS_TOKEN.

Search emails

Send a POST request with a JSON body to the Simple Search endpoint:

curl -X POST "https://cloud.jatheon.com/api/search/v1/simple?page=0&size=50&sort=-sentDate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerm": "invoice",
    "simpleSearchFields": ["subject", "body"],
    "dateRange": { "from": "2026-01-01T00:00:00", "to": "2026-03-31T23:59:59" }
  }'

Add these parameters to the URL:

• page — the page of results, starting from 0 (required)
• size — the number of results per page, up to 200 (required)
• sort — the field to sort by, such as sentDate, archivedDate, subject or size. Add a minus sign for descending order, for example -sentDate.

You can use these fields in the request body:

• searchTerm — the word, phrase or email address to search for
• simpleSearchFields — where to search: sender, recipients (To, Cc, Bcc and hidden recipients), subject, body and attachments
• dateRange — the sent date range, with from and to in the YYYY-MM-DDTHH:MM:SS format, in UTC (required). Set either one to null for an open range.
• subsearchTerm and subsearchFields — a second condition. An email must match both the search term and the subsearch term.
• fuzzy — set to true to also find similar spellings
• trackTotalHits — set to true to get an exact total for very large result sets

The response shows the number of matching emails in total, and the emails on this page in items. Each email has its id, subject, from, sent_date, archived_date, size, attachment_count and tags.

For example, to count the emails one person sent another in a week, search the sender with the first address and add the second address as a subsearch on the recipients:

{
  "searchTerm": "person.a@example.com",
  "simpleSearchFields": ["sender"],
  "subsearchTerm": "person.b@example.com",
  "subsearchFields": ["recipients"],
  "dateRange": { "from": "2026-10-19T00:00:00", "to": "2026-10-25T23:59:59" }
}

Please note that the API searches all mailboxes, so you don't need to list them. To limit a search to one person's email, search for their address in the sender and recipients fields. The mailboxes field only accepts mailboxes assigned to the API user, and any other address returns an error.

Open a single email

To see the full email, send a POST request with its id from the search results and the same JSON body:

curl -X POST "https://cloud.jatheon.com/api/search/v1/simple/details/EMAIL_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "searchTerm": "invoice", "simpleSearchFields": ["subject", "body"], "dateRange": { "from": null, "to": null } }'

The response includes the recipients (to, cc, bcc and hidden_recipients), the email text in body_text, and its attachments with their text content.

Please note that the single-email response is formatted for display. Words that match your search term are wrapped in HTML highlight tags, and the angle brackets around email addresses are HTML-encoded, for example < and >.

Limits and errors

You can send up to 30 search requests and 30 single-email requests per minute. Each response shows your remaining requests in the X-RateLimit-Remaining header. If you go over the limit, you'll get a 429 response: Rate limit exceeded. Try again in N seconds

Other responses you may see:

• 401 — the client ID or secret is wrong, or the access token is missing or expired. Get a new access token.
• 403 — the request isn't available through the API.
• 400 — the request isn't valid. The response explains why, for example Date range is a mandatory field., Subsearch fields are not valid or Simple Search contains invalid or illegal mailbox(es).

Every search and email view made through the API is recorded in the audit log, like searches in the app.

Related articles

• How to Perform a Simple Search
• How to View Audit Logs
• How to Set Custom Roles

Learn more about Jatheon Cloud, our cloud archiving solution.