List emails
Returns a page of emails, most recent first (by date, then by id). Use it to browse a mailbox, a folder, a saved view, or the emails hidden from the main inbox. For a keyword lookup, prefer GET /emails/search.
How the criteria combine:
- Without
folderType, every folder is listed, SPAM and TRASH included. PassfolderType=INBOXto read incoming mail only. - With
folderType=INBOXand noviewId, emails hidden by inbox filters (/filters) or by AI label rules withhideFromInbox: trueare left out.filtered=onlyreturns exactly those hidden INBOX emails instead. mailboxId,folderType,viewIdandfilterscombine with AND.- Known issue: when
searchhas 2 characters or more, the request is served by the search engine, which ignoresfilters,filtered=onlyand the inbox exclusion, and ranks results by relevance. Do not combinesearchwithfiltersuntil this is fixed. - Known issue: an unknown
viewIdreturns500 INTERNAL_ERRORinstead of a 404.
Pagination: pass nextCursor back as cursor. Stop on hasMore: false. nextCursor is not null on the last non empty page, only on an empty page.
The body is never included: fetch it with GET /emails/{emailId}/body. Every read is cancelled server side after 10 seconds (408 QUERY_TIMEOUT).
Authorization
apiKey Your 48 character Emelia API key, the same as for the Emelia API, sent as is (a Bearer prefix is tolerated). Create it at https://v3.emelia.io/settings/api. Disabling a key can take up to 5 minutes to apply to the Inbox API.
In: header
Query Parameters
Restrict to one mailbox (ids from GET /mailboxes). An unknown id returns an empty page.
Restrict to one system folder. Case sensitive; any other value is rejected with 400. Omitted, every folder is considered.
Value in
- "INBOX"
- "SENT"
- "DRAFTS"
- "SPAM"
- "TRASH"
Apply a saved view (ids from GET /views). The view filter tree and its mailbox restriction are combined with the other criteria. An unknown id currently returns 500 (bug).
only lists the INBOX emails hidden by inbox filters and by hideFromInbox AI labels (the app's "Filtered emails"). Any other value is rejected with 400. Forces the INBOX folder.
Value in
- "only"
JSON encoded filter tree (see the FilterNode schema). Bounds: 8192 bytes raw, 5 levels, 50 conditions in total, 500 characters per value. Unknown fields or operators are rejected. Known issue: an invalid date value is silently ignored instead of rejected.
length <= 8192Optional keyword. Shorter than 2 characters after trimming: ignored. Longer than 200: 400. When present, see the known bug above (filters are dropped).
length <= 200Opaque nextCursor from the previous page. Its format is not part of the contract.
Page size. Above 200 it is clamped to 200; an unreadable or non positive value falls back to 50 (no error).
1 <= value <= 20050Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/emails?mailboxId=cmbxacme0000000000000001&viewId=cmvwacme0000000000000001&filters=%7B%22id%22%3A+%22c1%22%2C+%22label%22%3A+%22sender_domain%22%2C+%22type%22%3A+%22equals%22%2C+%22value%22%3A+%22example.com%22%7D" \ -H "Authorization: YOUR_API_KEY"{ "items": [ { "id": "cmemacme0000000000000001", "mailboxId": "cmbxacme0000000000000001", "folderId": "cmfdacme0000000000000001", "messageId": "<CAJacme.0001@mail.example.com>", "threadId": "18c2acme0001", "subject": "Re: Partnership with Acme", "from": { "email": "jane.roe@example.com", "name": "Jane Roe" }, "to": [ { "email": "john.doe@acme.com", "name": null } ], "cc": [], "date": "2026-10-08T09:12:44.000Z", "snippet": "Thanks John, could we schedule a call next week?", "isRead": false, "isStarred": false, "isDraft": false, "waitingForReply": false, "hasAttachments": true, "attachments": [ { "filename": "brief.pdf", "size": 48213, "mimeType": "application/pdf" } ], "tags": [ { "id": "cmtgacme0000000000000002", "name": "Interested", "color": "#2563eb", "isAiLabel": true } ], "inReplyTo": "<20261008091500.acme01@acme.com>", "references": [ "<20261008091500.acme01@acme.com>" ] } ], "nextCursor": "2026-10-08T09:12:44.000Z|cmemacme0000000000000001", "hasMore": true}