PHP

Threads

`threads->list`, `listAll`, `iterate`, `get`, `update`, `trash`, `snooze`, `unsnooze` and `listAttachments`.

Reading

read_threads.php

$page = $client->threads->list(    folder: 'inbox',    query: 'from:ada',    labelIds: ['INBOX', 'IMPORTANT'],    limit: 25,); if ($page->nextCursor !== null) {    $nextPage = $client->threads->list(folder: 'inbox', cursor: $page->nextCursor);    echo count($nextPage), PHP_EOL;} $thread = $client->threads->get('CAHk7pQ2x9LmZ4-mail.example.com');echo $thread['messageCount'], ' ', $thread['hasUnread'] ? 'unread' : 'read', ' ', $thread['totalReplies'], PHP_EOL;

The API pages threads with a pageToken. The client hands it to you as nextCursor and takes it back as cursor:, like every other list, and listAll and iterate follow it for you. It is opaque: pass back what you were given and never build one.

The list filters are named arguments (labelIds:, dateFrom:), while the fields of a request body are array keys under the API’s names (addLabelIds on update). A thread comes back as an array keyed in camelCase, so $thread['messageCount'] reads the count.

sort_threads.php

use OpenEmail\Constants\ThreadSorts; $lastWeek = $client->threads->listAll(    sort: ThreadSorts::OLDEST,    dateFrom: new \DateTimeImmutable('-7 days'),    dateTo: new \DateTimeImmutable(),    fromContacts: true,);echo count($lastWeek), PHP_EOL; foreach ($client->threads->iterate(sort: ThreadSorts::SENDER) as $thread) {    echo $thread['id'], PHP_EOL;}

sort:, dateFrom:, dateTo: and fromContacts: are the thread list’s own controls. sort: is newest, oldest, sender or subject, and OpenEmail\Constants\ThreadSorts names them. The dates take a DateTimeInterface, sent as an instant in UTC, or an ISO 8601 string with a time and an offset, and both ends are included. A date string with no time is refused with a 422. fromContacts: true keeps mail whose newest message came from a saved contact. Every order pages to the end without skipping or repeating a thread.

listAll returns one array once the last page is in. iterate returns a Generator that yields each thread and fetches the next page only when the loop needs it, so a break stops the requests as soon as you have what you need.

Organising

organise_threads.php

$threadId = 'CAHk7pQ2x9LmZ4-mail.example.com'; $client->threads->update($threadId, ['read' => true, 'addLabelIds' => ['USER_DONE'], 'removeLabelIds' => ['INBOX']]); $client->threads->trash($threadId);$client->threads->snooze($threadId, new \DateTimeImmutable('+1 day'));$client->threads->unsnooze($threadId);

Read state is a label on every backend here, so it travels with the label lists, and the order is fixed when you set both: removals are applied before additions, so an id in both lists ends up on the thread. At least one of the three fields must be present.

addLabelIds takes ids from labels->list and the system ids such as ARCHIVE and STARRED. An id that names no label is refused with a 422 label_not_found rather than created, so make the label with labels->create first. $client->threads->list(folder: 'USER_DONE') lists every thread carrying a label, whichever folder it is in.

Attachments on a message

attachments.php

$files = $client->threads->listAttachments('CAHk7pQ2x9LmZ4-mail.example.com', 'message_4c1b257a'); foreach ($files as $file) {    echo $file['filename'], ' ', $file['contentType'], ' ', $file['size'], PHP_EOL;     $bytes = base64_decode($file['content'], true);     if ($file['content'] !== '' && $bytes !== false) {        file_put_contents(basename($file['filename']), $bytes);    }}

listAttachments returns a list of arrays. content is base64, which base64_decode() turns back into bytes, and it is an empty string when the stored bytes could not be found, so check it before decoding. The ciphertext of an encrypted message is in this list and downloads like any other file. The PGP/MIME version part and any detached signature are not. They keep their ids in encryption.parts and nothing more.

A message that arrived encrypted

This package neither encrypts nor decrypts. It cannot open a message somebody else encrypted, and it cannot send an encrypted one. The send request is refused if it carries an encryption marker, because a client with no key has no business asserting one. Keys generated in the OpenEmail app live in the browser that made them and reach nothing here. When that browser opens a sealed message the plaintext stays in it, and the stored message this call reads is still ciphertext. What threads->get gives you is the envelope, recognised. A message that arrived PGP- or S/MIME-wrapped carries an encryption array, so an empty decodedBody stops being the only thing you are handed. encryption is the one field of a message the API commits to, because it is the one whose absence you cannot survive guessing at.

encrypted_mail.php

use OpenEmail\OpenEmail; $thread = $client->threads->get('CAHk7pQ2x9LmZ4-mail.example.com'); foreach ($thread['messages'] as $message) {    if (!isset($message['encryption']) || !OpenEmail::isSealed($message)) {        continue;    }     error_log('cannot read this one: ' . $message['encryption']['format']);}

Branch with OpenEmail::isSealed(), never on the presence of the field. Two of the five formats, pgp-signed and smime-signed, describe a body that arrived in the clear beside a detached signature, so gating on presence hides mail nobody needed to hide, and the user cannot see it or explain it. OpenEmail::isSealed() exists for exactly that reason. The server states the sealed set once, the package’s copy is generated from that same source, and a third copy written out by hand is the copy that drifts. OpenEmail\Constants\MessageEncryptionFormats names all five formats.

Absence is not plaintext. encryption is missing on every message stored before detection shipped, and on anything that reached the mailbox by a path where the detector never ran. It records that nobody looked, a fact about our coverage rather than about the mail, and nothing backfills it.

Where these differ from the rest

Each entry in a thread’s messages is the array the mailbox stored, with no fixed list of fields, so read any key other than encryption with ?? null. Promising more would be the client asserting a normalisation nobody performs. encryption is the one field the API commits to anyway, because a client that cannot branch on it reads a sealed message as an empty one.
A request that cannot be served faithfully is a 422 capability_unsupported, thrown as a ValidationException, not a response that looks right and is quietly wrong.

Parameters: threads->list

folderstring: Which folder to list. The server defaults it to `inbox`, so leaving it out narrows the listing rather than widening it to everything. It applies to a `query:` search as well, unless the query names a folder itself with `in:` or a folder `is:` such as `is:sent`.
querystring: The mailbox search syntax. Plain words must all appear, and each matches loosely: case, accents and separators are ignored and part of a longer word counts, so `min` and `ben jamin` both find "Benjamin". A quoted phrase is matched as written apart from case and accents, so `"ben jamin"` does not find "Ben-Jamin", and filler words are dropped when something else is left to search for. When nothing matches exactly, close spellings are returned instead, so `benjimin` finds "Benjamin": a plain word, or the value of `from:`, `to:`, `cc:`, `subject:`, `body:`, `filename:` or `label:`, may differ from the start of a word by one typo (a changed, missing, extra or swapped letter) when it has four to seven letters and by two when it has eight or more. A quoted phrase, a word containing a digit, a shorter word and an excluded word still match exactly, and the pages that follow keep matching the same way. Narrow with operators such as `from:ada`, `label:Invoices`, `is:unread`, `has:pdf`, `before:2026/01/31` and `older_than:1y`, and combine them with `OR`, parentheses and a leading `-`. A value the search cannot use is ignored rather than narrowing. Words and the `from:`, `to:`, `cc:`, `subject:` and `body:` operators read the latest message’s sender, recipients, subject and the first 4,000 characters of its body with markup stripped, while `filename:` and `has:` read every attachment on the whole conversation, and labels and folders read the whole conversation. It narrows the same index the unfiltered listing reads. Sealed messages store no body text, so only their sender, recipients and subject can match. A plain word also matches the name of any attachment on the conversation, whichever message carried it.
labelIdsstring or array: Restrict the listing to threads carrying these labels. The endpoint takes a comma-separated string, and the client joins an array into one for you. There is no limit on how many you name.
limitint: How many threads to return, from 1 to 100. Left out, the handler uses 25. The default lives in the handler rather than the schema, so an absent value and an explicit 25 behave alike.
cursorstring: The previous page’s `nextCursor`, passed back verbatim. It is the API’s `pageToken` under the name every other list uses, and it is opaque, so never construct or edit one.

Response: OpenEmail\Result\Page

itemsarray: One array per thread in this page, lifted out of the API’s `data` envelope. Each one is only an `object` marker and an `id`. The listing carries no subject, snippet, participants or labels, so anything more means calling `threads->get` on the threads you want.
items[].idstring: The thread’s id, read as `$item['id']`, to hand to `threads->get`, `threads->update` and the rest unchanged. It is the same id whether the row came from a filtered listing or from a `query:` search.
hasMorebool: Whether there is a further page, taken from the API where it states one and derived from `nextCursor` where it does not.
nextCursorstring or null: The API’s `nextPageToken`, to send back as `cursor:` for the following page, or null when there is no further page. An empty token is normalised to null, so a null check is all the test you need.