how to build an AI agent portfolio update email daily summary

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'Portfolio Agent' });

console.log(inbox.address); // portfolio-agent@lobstermail.ai

No API keys to paste. No Google Cloud Console. The agent handles [its own signup](/blog/agent-self-signup-explained) and stores the token locally. If you want the summary to come from `updates@yourfirm.com` instead of a LobsterMail address, you can [set up a custom domain](/blog/custom-domains-agent-email) later.

## Step 2: connect your data sources

This is where most tutorials get vague. "Connect your data" isn't a step, it's a project. So let's be specific about the common sources.

**Brokerage APIs** like Alpaca, Interactive Brokers, or Schwab's new developer portal give you positions, balances, and order history via REST endpoints. Alpaca's `/v2/positions` returns JSON with current price, market value, unrealized P&L, and change percent for each holding. That's most of what you need.

**Database queries** work if you're pulling from a portfolio management system like Airtable, Snowflake, or even a Postgres table you maintain yourself. Write a query that returns yesterday's positions alongside today's, and compute the deltas in your agent logic.

**CSV or email-based feeds** are messier but common. Some brokers still email a daily statement as a PDF or CSV attachment. Your agent can receive these at its LobsterMail inbox, parse the attachment, and extract the structured data. The `inbox.receive()` method returns attachments with MIME types, so you can filter for `text/csv` or `application/pdf` and process accordingly.

The key principle: get the raw data into a JSON structure before you send it to your summarization model. Don't ask GPT-4 to "read" a PDF. Parse it first, then summarize the parsed data.

## Step 3: define your filters and thresholds

Not everything belongs in a daily summary. If you hold 40 positions and nothing moved more than 0.3%, the summary should say "quiet day" and stop. If one position dropped 8%, that should be the first line.

I use a simple tiering system:

- **Critical alerts**: any position moving more than 5% in a day, any margin call, any failed trade execution
- **Notable changes**: positions moving 2-5%, sector allocation shifting more than 1 percentage point, new dividends posted
- **Routine**: everything else, summarized as a table or skipped entirely

Define these thresholds in your agent's config, not in the LLM prompt. You want deterministic filtering before the model ever sees the data. The model's job is to write the summary in clear English, not to decide what's important. That's your logic.

## Step 4: choose your summarization model

For financial summaries, you want a model that follows formatting instructions precisely and doesn't hallucinate numbers. This rules out smaller open-source models for most production use.

Claude 3.5 Sonnet handles structured financial data well and follows output templates reliably. GPT-4 is comparable. Gemini 2.5 Flash is faster and cheaper if you're sending summaries at scale (say, to 50 clients with different portfolios).

The prompt structure that works best:
You are a portfolio analyst writing a daily summary email.

DATA:
{parsed_positions_json}

RULES:
- Lead with the net portfolio change (dollar amount and percentage)
- List critical alerts first, then notable changes
- Include a plain-text table of all positions with yesterday's close, today's close, and change %
- Keep the total summary under 300 words
- Do not add commentary or predictions. Facts only.

That last rule matters. You don't want your summary agent speculating about Fed policy. Facts, numbers, changes. If you want analysis, build a separate agent for that.

## Step 5: structure the email output

A good daily summary email has a predictable structure so you can scan it in 30 seconds. Here's what mine looks like:

**Subject**: `Portfolio update: +$1,247.30 (+0.8%) — Mar 7`

**Body**:
- One-sentence overview: "Your portfolio gained $1,247.30 yesterday, driven by NVDA (+3.2%) and offset by a dip in bonds."
- Alerts section (if any): critical moves, margin warnings, failed orders
- Top movers: 3-5 positions with the largest absolute or percentage changes
- Holdings table: every position, sorted by allocation weight
- Footer: "Generated by Portfolio Agent. Reply to this email to adjust your preferences."

That footer is useful. Because your agent has its own inbox, replies go back to the agent. You can wire up a simple intent parser so replying "stop including bonds" actually updates the filter config. That's a later optimization, but the architecture supports it from day one.

## Step 6: schedule and send

The sending part is straightforward:

```typescript
await inbox.send({
  to: 'you@yourfirm.com',
  subject: `Portfolio update: ${netChange} — ${date}`,
  text: summaryText,
  html: summaryHtml,
});