Collect and clarify project updates
Give recurring project reports a dedicated address, record what changed, and automatically ask contributors for missing information.
Read as Markdown ↗You receive weekly updates from outside contributors. They use ordinary email and sometimes attach a report; not all of them use your task system. A dedicated project address keeps that correspondence together without giving the agent your personal mailbox.
In this cookbook, the agent records each update and replies automatically when required information is missing. You get notes and a queue of exceptions instead of a stack of replies to approve.
For the other direction, using established information to answer incoming requests, see Answer project questions.
Assign the work once
Use the inbox assigned to the project. You authorize the ongoing job, including routine follow-up replies; individual messages within it need no further approval. Decide:
- Correspondents and purpose: which contributors send updates here, and which information the agent should collect.
- Sending authority: concise requests for missing information, not new deadlines, purchasing decisions, access changes or promises to do work.
- Processing and disclosure: which model and file tools may receive the correspondence, and which project facts may be shared with contributors.
- Runs and exceptions: when the check runs, and who reads its notes and the
updates/needs-reviewqueue.
From addresses can be forged, so keep anything that needs a verified sender out of the assignment. The agent replies only to listed correspondents; sending rules can restrict the inbox's recipients as well.
Run it one way per inbox: through your connected agent, with no extra keys, or as our program, with a Cherami key and an OpenAI key.
Follow an update through the workflow
Suppose a contributor writes, “The drawings are complete. The site visit is blocked,” and attaches a short text report. The agent saves a note describing the reported progress and blocker. If the assignment requires the next step and responsible person, it replies asking for those details. It does not invent a resolution or ask you to approve that routine question.
Each run:
- Finds unprocessed messages. It lists the inbox's mail without
updates/handledorupdates/needs-review, oldest first, and reads each one. - Reads enough context. It reads the new text of each reply, the full original when answers are inline or forwarded, and relevant attachments.
- Records and acts. It saves the note and the exact reply before sending, replies only within the assignment, records complete updates without an acknowledgment, and sets aside exceptions.
- Labels the result. It checks the sending outcome, then adds the progress label.
updates/handled means the update has a saved note and either needed no reply or its follow-up was accepted for delivery. A later reply from the contributor is new work. updates/needs-review holds updates the agent set aside for you; nobody is notified, so check the queue.
To build it yourself over HTTP, follow the same steps with received messages, attachment downloads, replies and labels.
Run it through your connected agent
With Cherami connected, give your agent the project assignment, contributor list and approved context. It uses its own reasoning and file tools, so it needs no OpenAI key. An assignment can say:
Check the assigned project inbox now. Record each contributor's reported progress, blockers and next steps in our project notes. Automatically ask for required information missing from an update, within the contributor and disclosure boundaries we agreed. Do not ask me to approve routine follow-ups. Record complete updates without an acknowledgment. Set aside decisions or unsupported files for my review. Check up to three times, fifteen seconds apart, reading at most 60 messages each time, and stop after five minutes or three replies. Report the notes, exceptions and any backlog left when you stop.
The tools that carry it out:
list_messageswith the assignedinbox_id,labels_none: ["updates/handled", "updates/needs-review"],order: "oldest"andlimit: 20, followingnext_cursorwith the same filters.get_messagereads each ready message;format: "full"returns original bodies and headers, andget_threadsupplies earlier conversation context.read_attachmentwith the message and attachment IDs, decoding its base64 chunks and followingnext_offsetuntil it is null. Files the agent can't read go to review.reply_message, after checking its derived recipients against the assignment and saving the note, the exact arguments and a uniqueidempotency_key. If a reply gets no response, retry with the same key and arguments.update_message_labelson the received message:updates/handledonce the reply'smessage.statusisacceptedor no reply was needed,updates/needs-reviewotherwise. Messages still processing wait for the next run.
Run our program
Both versions below are complete programs using the published Cherami SDK, with an OpenAI Responses API call for the reasoning step; you can swap that call for your own model. OpenAI access and model charges are separate from Cherami. Run one copy per inbox, always with the same state directory.
Prepare the assignment and state
Choose a state directory for this workflow and write an assignment.json, replacing the inbox ID and correspondent addresses with yours:
{
"workflow": "updates",
"inbox_id": "YOUR_ASSIGNED_INBOX_ID",
"correspondents": ["alex@example.com", "sam@example.com"],
"model": "gpt-4.1",
"context": "You collect weekly updates for the Riverside documentation project. Record reported progress, blockers, next steps and the person responsible for each next step. Ask the contributor for required information missing from their update. Do not ask again for information already present in the message or its attachment. Record complete reports without replying. Escalate requests for decisions, budget, new commitments or changes to the assignment. Do not respond to acknowledgments or automated notices. Only the reporting requirements in this assignment may be shared; do not disclose another contributor's correspondence."
}The model must support structured output through the Responses API; any such model available to your OpenAI account works in place of gpt-4.1. Mail bodies, supported attachment text and this context go to OpenAI, with store: false requested.
Set these environment variables, supplying the keys privately:
| Variable | Value |
|---|---|
CHERAMI_API_KEY | Your Cherami key |
OPENAI_API_KEY | Your OpenAI key |
WORKFLOW_ASSIGNMENT | Path to the assignment JSON |
WORKFLOW_STATE | Path to this workflow's state directory |
The state directory holds each message's summary, planned reply and send receipts. The TypeScript and Python versions each need their own.
TypeScript
Requires Node.js 24+ or Bun. In your application directory, install the SDK and download the program:
bun add @cherami/sdk
curl --fail --silent --show-error \
https://cherami.to/cookbooks/email-workflow.mts \
--output email-workflow.mtsWith the assignment and environment set, this command can send replies automatically (source):
bun run email-workflow.mtsOn Node.js, install the SDK with npm install @cherami/sdk and run node email-workflow.mts.
Python
Requires Python 3.11+; the run command below uses uv. Download the program:
curl --fail --silent --show-error \
https://cherami.to/cookbooks/email-workflow.py \
--output email-workflow.pyWith the same assignment and environment, this command can send replies automatically (source):
uv run --with cherami --with httpx email-workflow.pyIn an existing Python application, install cherami and httpx with your usual tooling instead.
Know what this example processes
Each run checks the inbox up to three times, fifteen seconds apart, reading up to 60 messages each time. It sends at most three replies and stops after five minutes, so schedule it to run again; it tells you when a backlog remains.
It reads up to three plain-text, Markdown, CSV or JSON attachments of up to 64 KiB each. A message with anything else, such as a PDF, goes to review; to handle other formats, add your own reader (attachments).
The model reads the extracted reply text first and can ask once for the original bodies.
The program replies only to a listed correspondent, and only when the message's From and reply address are that same address; anything else goes to review. The model can't choose recipients, attach files or use tools: it returns a private summary, a reply body and whether to reply, record, escalate or read the full message.
Read the result and recover interruptions
The state directory has one folder per received message:
MESSAGE_ID/
plan.json
receipt-UNIQUE_ID.jsonplan.json holds the summary, the decision and, for a reply, the saved send. The console shows only message IDs and labels, so read the summaries there.
| Result | Label |
|---|---|
| No reply needed | updates/handled |
| Reply accepted for delivery (accepted is not delivered) | updates/handled |
| Anything else | updates/needs-review, with the result saved in the message's folder |
To clear a review item, read its plan.json and receipt, handle it yourself, then label it updates/handled.
If a run stops partway, run it again with the same state directory within 24 hours: it finishes the saved work without sending twice. If the rerun stops at once because run.lock exists, make sure the earlier run has stopped, then delete only that file.