canonical: https://jentic.com/apis/dacid99.gitlab.io/eonvelope

# Dacid99 Eonvelope API

Eonvelope is a self-hostable email archiving application with a web interface and integrations for Grafana, Paperless-ngx, and Searxng. The API exposes eight endpoints covering archived email listing, retrieval of raw EML content, attachment download, full-text search, and archive statistics. Operators run Eonvelope on their own infrastructure and use the API to expose archived mail to other tooling without building a connector to the underlying mail store.

## For AI agents

List, search, and retrieve archived emails and attachments from a self-hosted Eonvelope archive for compliance and research workflows.

## Scope

Does not handle live mailbox access, sending mail, or inbound mail routing - use for searching and retrieving content from an existing Eonvelope archive only.

## Capabilities

- List archived emails with pagination across the Eonvelope store
- Retrieve a specific archived email by email_id with structured metadata
- Download the raw EML source of an archived email for forensic or evidentiary use
- Enumerate and download attachments associated with an archived email
- Run full-text search across the archive via GET /search
- Retrieve archive statistics for capacity planning and reporting

## Use cases

### Compliance Search and Export

When a compliance request requires extracting all archived mail relating to a customer or legal matter, an operator runs GET /search with the relevant query, walks the results to GET `/emails/{email_id}/raw`, and stores each EML file as evidence. The agent automates the export, which would otherwise take hours of manual work in a webmail UI.

Example prompt: Call GET /search?q=customer@example.com, then loop the result IDs through GET `/emails/{email_id}/raw` and write each response to disk.

### Attachment Recovery Workflow

Users who need to recover an attachment from an archived email use GET `/emails/{email_id}/attachments` to enumerate attachments, then GET `/emails/{email_id}/attachments/{attachment_id}` to download the file. This makes Eonvelope a useful self-hosted alternative to enterprise archiving products for small teams.

Example prompt: Given email_id 'abc123', call GET `/emails/abc123/attachments`, pick the first attachment, and GET `/emails/abc123/attachments/{attachment_id}.`

### Archive Capacity Reporting

Operators of self-hosted Eonvelope instances need periodic visibility into how many emails are stored and how the archive is growing. GET /stats returns counts and storage figures that can be piped into a Grafana dashboard, replacing manual SSH checks against the underlying database.

Example prompt: Call GET /stats once a day and write the email_count and storage_bytes fields to a Prometheus pushgateway for Grafana.

### Agent-Assisted Mail Research

An AI research assistant indexes a project mailbox by listing emails through GET /emails, retrieving relevant ones with GET `/emails/{email_id}`, and answering questions over the archive. The Bearer token is stored in Jentic so the agent never sees the raw secret, which matters when the archive contains confidential correspondence.

Example prompt: Call GET /search?q=project-name, retrieve the top 20 emails via GET `/emails/{email_id}`, and summarise key decisions.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/emails` | List archived emails |
| GET | `/emails/{email_id}` | Get a specific archived email |
| GET | `/emails/{email_id}/raw` | Download raw EML source |
| GET | `/emails/{email_id}/attachments` | List attachments for an email |
| GET | `/emails/{email_id}/attachments/{attachment_id}` | Download a single attachment |
| GET | `/search` | Full-text search across archived emails |
| GET | `/stats` | Get archive statistics |
| DELETE | `/emails/{email_id}` | Delete an archived email |

## Key resources

- **Emails** — Archived email records and raw EML retrieval
- **Attachments** — Enumerate and download attachments for an archived email
- **Search** — Full-text search across the archive
- **System** — Archive statistics endpoint

## Why Jentic

- **Setup:** Wiring Eonvelope by hand means learning its bearer auth, resolving the deployment's server_url base, and building the paging and retrieval plumbing for an email archive yourself. Through Jentic you install once, import the Eonvelope API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Eonvelope puts the email id in the URL path (`/emails/{email_id}/...`), so a rule can pin your agent to one archived email for reading its content, raw form, and attachments. You choose the operations it may call, so deletion is not included unless you add it.
- **Credential handling:** Your Eonvelope bearer token and the deployment's server_url are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search archived emails' or 'download the raw EML for an archived email', and Jentic returns the matching Eonvelope operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Gmail API** — Hosted mail provider API focused on live mailbox access rather than self-hosted archive retrieval.
- **Dropbox API v2** — Object storage to write exported EML files into for sharing or further processing.
- **Box Content API** — Enterprise content storage for compliance-grade archives of exported emails.

## FAQ

### What authentication does the Eonvelope API use?

Eonvelope uses HTTP Bearer authentication. You generate a token in the self-hosted instance and pass it as Authorization: Bearer <token> on every request to {server_url}/api. Through Jentic the token is stored encrypted in the vault and the agent receives a scoped runtime credential, so the raw token never lands in chat or logs.

### Can I full-text search archived emails through the API?

Yes. GET /search accepts a query parameter and returns matching email records. Combine it with GET `/emails/{email_id}` or GET `/emails/{email_id}/raw` to retrieve the full content for each hit.

### What are the rate limits for the Eonvelope API?

Eonvelope is a self-hosted application, so any rate limits are determined by the deployment rather than a SaaS tier. Treat the underlying database as the bottleneck and pace bulk exports to keep the archive responsive for interactive users.

### How do I export archived emails through Jentic?

Install pip install jentic and run an agent with the search query 'export archived emails as EML'. Jentic returns the GET /search and GET `/emails/{email_id}/raw` operations with their input schemas, so the agent can iterate the search results and stream the raw EML for each hit.

### Can I delete an email from the Eonvelope archive via the API?

Yes. DELETE `/emails/{email_id}` removes the email and its attachments. Use this carefully because Eonvelope is intended as an archive of record; deletion should be gated on a retention policy review.

### Is the Eonvelope API free?

Eonvelope itself is open source and self-hosted, so there is no per-call cost. Your costs are limited to the infrastructure you run it on; the API is included with any Eonvelope deployment.

### Can I limit what my agent is allowed to do with the Eonvelope API?

Yes. Because you run Jentic One yourself, your own rules decide which Eonvelope operations and credentials the agent may use. Eonvelope puts the email id in the URL path, such as `/emails/{email_id}` and `/emails/{email_id}/raw`, so you can pin the agent to reading a single archived email, its raw EML, and its attachments while withholding the full listing or search. You choose the operations the agent may call, so a destructive DELETE `/emails/{email_id}` is excluded unless you explicitly allow it.