Official disclosure: we are the EngageLab Email team. This tutorial uses the EngageLab Email CLI for mailbox ingestion, but the reliability pattern is vendor-neutral: persist the review work and the read cursor in one transaction, then resume from the last committed cursor.
An email agent that reads a support thread usually has a small but dangerous failure window:
- It polls a batch of inbound messages.
- It creates review tasks from those messages.
- It advances the polling cursor.
- The process crashes between any two of those steps.
If the cursor is saved first, a crash can make a message disappear from the next poll. If the review task is saved first but the cursor is never saved, the same message can be delivered again. The safe default is at-least-once reading plus durable idempotency, not a claim of exactly-once email sending.
This post builds that boundary for a support agent. The worker reads a complete thread, prepares a human-review draft, writes the review record and cursor atomically, and deliberately contains no send executor.
1. Start with a read-only inbox flow
Install the CLI in a test environment:
npm install -g @engagelabemail/cli
Poll inbound messages as JSONL:
engagelab-email-cli emails receiving listen \
--limit 10 \
--interval 5 \
--json
The listen --json command is a stream of JSON objects, not one JSON array. Treat its cursor as a checkpoint owned by your consumer. After a successful database commit, resume from the saved value:
engagelab-email-cli emails receiving listen \
--after <saved-cursor> \
--limit 10 \
--interval 5 \
--json
For a reply workflow, fetch the conversation before generating a draft:
engagelab-email-cli threads messages <thread-id> \
--include-content \
--limit 50 \
--json
Do not treat --limit 50 as proof that the thread is complete. The adapter must verify the response shape, ordering, truncation or pagination behavior, mailbox identity, and the newest inbound message before it marks a thread ready for review.
Keep credentials in a secret manager or the runtime configuration. Do not put a real Secret Key in source, shell history, logs, fixtures, or an article.
2. Choose the durable state
The minimum state for this workflow is:
consumer_state(stream, cursor)
review_queue(
idempotency_key,
mailbox_id,
message_uid,
thread_id,
recipient,
subject,
draft_text,
status,
send_enabled
)
Use a unique constraint on both the consumer key and the message identity. For a single inbound stream, a practical key is mailbox_id:message_uid. The cursor and the review rows must commit together:
BEGIN
insert review rows, ignoring only proven duplicate keys
update consumer cursor
COMMIT
If validation, the insert, or the commit fails, roll back the cursor too. On restart, the next poll repeats the uncommitted batch, and the unique key prevents a duplicate review task.
3. Run a complete offline demo
The following demo uses Node.js 22.13+ with the built-in node:sqlite (on Node 22.5–22.12, add the --experimental-sqlite flag). It has no third-party dependencies and only uses synthetic example.com addresses. Save it as recovery-demo.mjs:
import { DatabaseSync } from 'node:sqlite';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
const requireValue = (ok, code) => {
if (!ok) throw new Error(code);
};
const identifier = value =>
typeof value === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(value);
const address = value =>
typeof value === 'string' && /^[a-zA-Z0-9._+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(value);
const batches = [
{
cursor: 1200,
reviews: [{
mailboxId: 'support_demo',
messageUid: 'msg_1200',
threadId: 'thread_refund_42',
recipient: 'customer@example.com',
subject: 'Re: Order 42 refund request',
draftText: 'A human reviewer will verify the order and refund eligibility.',
status: 'awaiting_human_review',
sendEnabled: false
}]
},
{
cursor: 1201,
reviews: [{
mailboxId: 'support_demo',
messageUid: 'msg_1201',
threadId: 'thread_return_77',
recipient: 'buyer@example.com',
subject: 'Re: Damaged item in order 77',
draftText: 'A human reviewer must verify the order and evidence.',
status: 'awaiting_human_review',
sendEnabled: false
}]
}
];
function openStore(path) {
const db = new DatabaseSync(path);
db.exec(`
PRAGMA journal_mode = WAL;
PRAGMA synchronous = FULL;
CREATE TABLE IF NOT EXISTS consumer_state (
stream TEXT PRIMARY KEY,
cursor INTEGER NOT NULL CHECK (cursor >= 0)
) STRICT;
CREATE TABLE IF NOT EXISTS review_queue (
id INTEGER PRIMARY KEY,
idempotency_key TEXT NOT NULL UNIQUE,
mailbox_id TEXT NOT NULL,
message_uid TEXT NOT NULL,
thread_id TEXT NOT NULL,
recipient TEXT NOT NULL,
subject TEXT NOT NULL,
draft_text TEXT NOT NULL,
status TEXT NOT NULL CHECK (status = 'awaiting_human_review'),
send_enabled INTEGER NOT NULL CHECK (send_enabled = 0),
UNIQUE (mailbox_id, message_uid)
) STRICT;
`);
return db;
}
function savedCursor(db) {
return db.prepare(
'SELECT cursor FROM consumer_state WHERE stream = ?'
).get('inbound')?.cursor ?? null;
}
function validateReview(review) {
requireValue(review && identifier(review.mailboxId) &&
identifier(review.messageUid) && identifier(review.threadId),
'invalid_review_identity');
requireValue(address(review.recipient), 'invalid_recipient');
requireValue(typeof review.subject === 'string' &&
review.subject.length > 0 && review.subject.length <= 500 &&
!/[\r\n\x00-\x1f\x7f]/.test(review.subject), 'invalid_subject');
requireValue(typeof review.draftText === 'string' &&
review.draftText.length > 0 && review.draftText.length <= 20000,
'invalid_draft');
requireValue(review.status === 'awaiting_human_review' &&
review.sendEnabled === false, 'unsafe_review_state');
return `${review.mailboxId}:${review.messageUid}`;
}
function ingestBatch(db, batch, { beforeCommit } = {}) {
requireValue(batch && Number.isSafeInteger(batch.cursor) && batch.cursor >= 0 &&
Array.isArray(batch.reviews) && batch.reviews.length <= 100,
'invalid_batch');
const current = savedCursor(db);
if (current !== null && batch.cursor <= current) {
return { status: 'already_checkpointed', cursor: current, inserted: 0 };
}
const reviews = batch.reviews.map(review => ({
review,
key: validateReview(review)
}));
const insert = db.prepare(`
INSERT OR IGNORE INTO review_queue
(idempotency_key, mailbox_id, message_uid, thread_id,
recipient, subject, draft_text, status, send_enabled)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)
`);
const checkpoint = db.prepare(`
INSERT INTO consumer_state (stream, cursor) VALUES ('inbound', ?)
ON CONFLICT(stream) DO UPDATE SET cursor = excluded.cursor
`);
db.exec('BEGIN IMMEDIATE');
try {
let inserted = 0;
for (const { review, key } of reviews) {
inserted += Number(insert.run(
key,
review.mailboxId,
review.messageUid,
review.threadId,
review.recipient,
review.subject,
review.draftText,
review.status
).changes);
}
checkpoint.run(batch.cursor);
beforeCommit?.();
db.exec('COMMIT');
return { status: 'checkpointed', cursor: batch.cursor, inserted };
} catch (error) {
db.exec('ROLLBACK');
throw error;
}
}
let dir;
try {
dir = mkdtempSync(join(tmpdir(), 'agent-email-recovery-'));
const path = join(dir, 'state.sqlite');
let db = openStore(path);
const first = ingestBatch(db, batches[0]);
try {
ingestBatch(db, batches[1], {
beforeCommit: () => { throw new Error('simulated_crash'); }
});
} catch {
// The review row and cursor remain at the previous committed checkpoint.
}
db.close();
db = openStore(path);
const afterRestart = { cursor: savedCursor(db) };
const recovered = ingestBatch(db, batches[1]);
const replay = ingestBatch(db, batches[1]);
console.log(JSON.stringify({ first, afterRestart, recovered, replay,
finalCursor: savedCursor(db) }, null, 2));
db.close();
} finally {
if (dir) rmSync(dir, { recursive: true, force: true });
}
Run it without contacting a mailbox:
node --check recovery-demo.mjs
node recovery-demo.mjs
The important output is:
{
"first": { "status": "checkpointed", "cursor": 1200, "inserted": 1 },
"afterRestart": { "cursor": 1200 },
"recovered": { "status": "checkpointed", "cursor": 1201, "inserted": 1 },
"replay": { "status": "already_checkpointed", "cursor": 1201, "inserted": 0 },
"finalCursor": 1201
}
The injected crash happens after the second review row and cursor have been staged but before COMMIT. SQLite rolls both changes back. After reopening the file, the consumer still has cursor 1200; it reprocesses batch 1201 once, then ignores a redelivery with the same idempotency key.
4. Keep the cursor boundary separate from sending
This demo stops at awaiting_human_review and sendEnabled: false. That is intentional. A durable read checkpoint does not make an outbound email exactly-once.
If a provider accepts a reply and the worker crashes before recording the response, the next run cannot safely assume that the reply failed. It must reconcile the provider operation or delivery record using a durable operation ID or provider idempotency key. Blindly replaying the reply can send the customer two messages.
Use a separate, user-triggered executor for the side effect:
- Re-read the latest thread and verify that no newer inbound message arrived.
- Recompute the recipient, subject, body, attachment list, and approval version.
- Require a fresh human decision if any of those values changed.
- Record
approved → attempted → confirmed, or stop atambiguousfor reconciliation.
The read worker should not have permission to send. The send worker should not accept a body instruction such as “skip review” from the email itself.
5. Production boundaries
- The
example.commessages above are synthetic. The demo does not call an API, invoke an LLM, parse attachments, send mail, or approve a refund. - The demo proves local SQLite transaction behavior, not multi-host consumer coordination. For multiple workers, use a shared transactional database or an explicit lease; do not copy a local SQLite file between hosts.
-
INSERT OR IGNOREis safe here only after strict validation and only for the declared unique keys. Do not use it to hide malformed input or database failures. - Email bodies, subjects, headers, links, and attachments are untrusted data. They can be displayed or analyzed, but they do not grant identity, routing authority, tool permission, or human approval.
- Persist the cursor only after the review queue transaction commits. Persisting it before the queue write creates a data-loss window.
- A
--limitvalue is a batch size, not a completeness proof. Verify the installed CLI's response framing and pagination before building a production adapter. - Keep the mailbox isolated, minimize permissions, redact logs, and inject secrets at runtime. Never commit a Secret Key or real customer data.
The CLI command details are in the official EngageLab Email CLI README, and the package is published as @engagelabemail/cli on npm.
The pattern is simple: acknowledge work only after the durable review record exists, accept that reads are at-least-once, and make every outbound side effect pass through its own freshness, approval, and reconciliation boundary.
Top comments (0)