How I Turned Broker Emails Into a Self-Updating Trading Journal

Amol Godbole — Sun, 25 Oct 2026 17:01:27 +0000

Disclosure: The Sensible Trader, the product discussed in this article implements an agentic solution for broker-email automation. This is an engineering account of how I built and tested the workflow, not investment advice or a performance claim.

Broker confirmations already contain the fills. The engineering challenge is turning those emails into trustworthy position state without duplicating trades, guessing at ambiguous events, or mishandling rolls and assignments.

TL;DRI built an early-access system that reads broker-confirmation emails and updates The Sensible Trader automatically. The useful part was not extracting a ticker and price. It was building a state machine around messy real-world events: multiple fills, partial closes, rolls, assignments, duplicate notifications, and confirmations the parser cannot safely understand. This article explains the architecture, the safeguards, the failures that shaped it, and why uncertain events go to a human review queue instead of being guessed.

I did not set out to build an email parser.

I wanted an honest answer to a simple question:

What do I actually hold right now?

That sounds trivial until an options position has been opened in several fills, partially closed, rolled to another strike, assigned, or spread across more than one brokerage account. A spreadsheet can preserve every row and still lose the meaning of the position.That was the failure I kept running into. My transaction history was complete, but my position state was not. A buy and a sell could appear as unrelated entries. A rolled covered call could look like a realized loss plus a new naked call. An assignment could close an option while leaving the underlying shares unchanged. The rows were technically present, yet the answer to “what remains open?” was wrong.

So I built a different workflow for The Sensible Trader: let broker-confirmation emails become the event stream, then reconstruct position state from those events.The system is in early access, and I use it on my own journal. It is not finished, and it does not pretend to understand every broker message. The interesting engineering lesson has been this: automation becomes useful only after it learns when not to act.

The inbox is already an event stream

Every executed order creates a broker record. For many retail brokers, a confirmation also lands in email with the details needed to journal the event: symbol, option type, strike, expiration, action, quantity, execution price, and time.That made the inbox a practical integration surface. It avoided collecting broker passwords and did not require a separate manual-entry habit. The user connects the Gmail inbox that actually receives broker confirmations; it may be different from the address used to create the journal account.The watcher uses read-only Gmail access. It first narrows the mailbox with sender and subject rules, then retrieves only matching messages.

The pipeline runs every few minutes during the US market-day window. Frequency is not the hard part. Correctness is.

Parsing a fill is easier than understanding it

The first version extracted fields from a confirmation and posted them to the journal. That worked for a clean, single-leg opening trade. It was not enough for real trading.A parser can tell me that an email says “sold two calls.” The journal still has to decide whether that event:

opens a covered call against shares;
opens a short call against a long call, as in a poor man’s covered call;
adds to an existing short position;
partially closes a long-call position;
closes the old leg of a roll;
represents an assignment rather than an ordinary sale.

Those decisions require current position state, not just text extraction.

I ended up separating the system into two layers.

A registry-driven parser converts each supported broker format into a normalized execution event.

A second layer matches that event against the user’s open positions and applies the appropriate state transition.

The registry is global because broker formats are global. User trades, processed-message IDs, review items, and analytics remain isolated per user. When a broker changes its confirmation format, the reusable knowledge is the pattern—not anyone’s trade data.

The normal form: one execution, explicit meaning

Every recognized message is converted into a small event with explicit semantics:

{ "broker": "recognized-broker", "asset_type": "option", "symbol": "XYZ", "action": "sell_to_close", "quantity": 2, "strike": 100, "right": "call", "expiration": "YYYY-MM-DD", "execution_price": 4.25, "executed_at": "broker-reported timestamp"}

The example is deliberately generic. The important part is that the system does not let free-form email language leak into journal logic. “Sold,” “closed,” “assigned,” and “rolled” are not interchangeable actions.

Normalization also makes validation possible. Quantity must be positive. The expiration must be a valid date. An option needs a strike and a right. Price units must match the journal’s convention. A close must match a compatible open position.If those checks fail, the event does not become a trade.

Deduplication is a financial control, not housekeeping

A watcher that runs every few minutes will see the same confirmation repeatedly. Retries also happen after network failures. Email providers can return the same message in more than one search. Some brokers send several fills with nearly identical text.Posting twice is worse than missing a dashboard refresh. It changes position size and P&L.

The system therefore keeps two dedup keys:

Gmail message ID - prevents the same email from being processed twice.

Execution fingerprint- prevents the same execution from being posted again through a duplicate notification or replay.The fingerprint uses normalized execution fields plus the message identity. That last piece matters: two legitimate fills can have the same ticker, contract, quantity, price, and minute. Collapsing them into one would be as wrong as posting one twice.A retry must be safe. If a write succeeds but the worker loses the response, the next run should converge on the same journal state rather than create another trade.

Multiple fills must stay multiple fills

Brokerage interfaces often summarize several fills into one average price. That is useful for a quick position view, but it is not enough for an audit trail. If eight contracts were accumulated across seven executions, the journal should preserve seven entry events. The position can still show a weighted average cost, but the underlying fills must remain available for reconstruction, charting, and debugging.

This distinction exposed several bugs in my own reporting. A recap chart looked plausible while plotting one average entry instead of seven real executions. The fix was not to move a marker. It was to make individual broker fills the source of truth all the way through the pipeline. That rule now applies to ingestion as well as visualization:

never invent a synthetic fill merely because an average is easier to display.

Rolls are campaigns, not isolated rows

A roll is where transaction-first journals get into trouble.Suppose I buy back a short covered call and sell another call at a later expiration. If the system treats those as unrelated records, it can produce two dangerous distortions:

the new short call appears naked even though shares or a long call still cover it;

the debit on the closed leg is presented as the final result even though the replacement leg remains open.

The state model links both legs to the same campaign. The old leg closes; the replacement leg opens with its correct coverage. The underlying shares are not sold merely because the option strike changed.For reporting, realized P&L on the closed leg can be calculated, but the roll campaign should not be described as finished while the replacement remains open. That is a product-language rule backed by accounting state.

Assignments require two state changes

Assignment notices taught me another version of the same lesson. An assigned short call is not only an option close. Shares are called away. An assigned short put is not only an option close either. Shares are put into the account. The agent handles a recognized assignment notice as two linked actions:It also checks whether another system has already recorded either action before writing anything. That avoids the particularly ugly failure mode where an assignment sweep and an email watcher both sell the same shares.Warnings about possible early assignment are not assignments. They are ignored rather than converted into trades.

The close guard catches plausible-looking mistakes. Closing a position is where a parser’s confidence can become expensive.Before posting a close, the pipeline checks the action, instrument, contract, quantity, execution price, covering position, and original premium. A close must match an actual open position, and its execution price must agree with the broker confirmation within a small tolerance.One production incident revealed a subtle exception. An older open record had a zero premium because of bad historical data. The original guard rejected the close, leaving the option incorrectly open. That stale state later exposed the position to incorrect assignment handling.The safer rule is now:

If the broker confirms a valid close but the open premium is zero or unknown, record the close at the verified execution price and flag it for review. Do not leave a closed position open merely because historical cost data is incomplete.The journal may not be able to calculate final P&L until the opening premium is corrected, but the position state remains truthful.

Uncertainty goes to a review queue

When a message is unknown, ambiguous, or cannot be matched confidently, the agent creates a review item. The user can approve, edit and approve, or dismiss it in the journal UI. Nothing is silently dropped, and nothing financially meaningful is guessed.That queue also makes the system extensible. A new parser can be added after a format is understood, while the original email remains the evidence for resolving the current event.

Credentials should not be part of the parser

The watcher needs two connections: read-only access to the broker-email inbox and authenticated access to the journal API.The journal key is collected through a secure connector rather than chat, source code, environment variables, or log files. The agent receives a short-lived surrogate that the platform replaces only when the request goes to the approved API host. The raw key is never available to the parsing code.That separation follows the broader principle in [OWASP’s guidance on protecting cryptographic keys] (sensitive keys belong in managed storage with access control and auditing, not embedded in application logic.

The Gmail connection is also scoped to the inbox that receives confirmations. It does not need the user’s broker login.

What changed in my product thinking

I started with a feature idea: remove manual trade entry.I ended up with a reliability problem: reconstruct the truth from an imperfect stream of external events.That changed my priorities.

First state beats activity.

A ledger of fills is useful only if it can answer what remains open, what is covered, and what has actually been realized.

Second, every automation needs an abstain path.

A review queue is not evidence that the agent failed. It is evidence that the system refused to manufacture certainty.

Third, incidents should become invariants.

When a roll is mislabeled, an assignment duplicates a share sale, or multiple fills collapse into one marker, the durable fix belongs in the parser, state model, or template—not in one corrected record.

Fourth, observability must verify outcomes.

A worker saying “posted” is not proof that a journal record exists. The source of truth is the resulting journal state, backed by execution IDs and API responses.

In Passing

The surprising part was not that email could replace a form. It was that a mundane inbox could become a reliable event source—once deduplication, state transitions, review, and failure handling were treated as the product rather than implementation details.

DEV Community: Amol Godbole

Checkout my latest blog that turns email conformations into an event stream using Meta Muse !