Pip Says Hello

Create a new directory

mkdir pip-agent && cd pip-agent

Initialize the SST project

SST (Ion) is an infrastructure-as-code framework that makes deploying to AWS feel like writing application code. Check sst.dev for the latest install instructions — the CLI evolves fast.

npx sst@latest init

Follow the prompts. Pick aws as the provider. This creates a sst.config.ts and a tsconfig.json.

Set up your package.json

Replace the generated package.json with this. It pulls in the AWS SDK clients we need — Bedrock for Claude, SES for email, S3 for reading inbound mail, and DynamoDB (we'll need it in Part 2, but installing it now saves a trip back).

{
  "name": "pip-agent",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "sst dev",
    "deploy": "sst deploy --stage prod",
    "remove": "sst remove --stage prod"
  },
  "dependencies": {
    "@aws-sdk/client-bedrock-runtime": "^3.700.0",
    "@aws-sdk/client-dynamodb": "^3.700.0",
    "@aws-sdk/lib-dynamodb": "^3.700.0",
    "@aws-sdk/client-ses": "^3.700.0",
    "@aws-sdk/client-s3": "^3.700.0",
    "mailparser": "^3.7.0"
  },
  "devDependencies": {
    "sst": "^3.0.0",
    "typescript": "^5.5.0",
    "@types/aws-lambda": "^8.10.0",
    "@types/mailparser": "^3.4.0",
    "@types/node": "^22.0.0"
  }
}

Install dependencies

npm install

Create the source directory

mkdir -p src/lib

This is where all your Lambda handlers and helper modules will live.

App config

Start with the shell. This names your app and sets the region. We're using us-east-1 because SES inbound email and Bedrock both work there, and keeping everything in one region avoids a lot of confusion.

export default $config({
  app(input) {
    return {
      name: "pip-agent",
      removal: input?.stage === "prod" ? "retain" : "remove",
      home: "aws",
      providers: {
        aws: {
          region: "us-east-1",
        },
      },
    };
  },
  async run() {
    // We'll fill this in next
  },
});

The removal setting tells SST what to do when you tear down a stage. In dev, remove everything. In prod, retain resources so you don't accidentally delete your data.

Add Secrets for your inbox and duck address

Inside the run() function, add two secrets. UserEmail is where Pip sends messages. DuckEmail is the SES-backed address Pip sends from and receives replies on.

// --- Human inbox + duck reply address ---
const userEmail = new sst.Secret("UserEmail");
const duckEmail = new sst.Secret("DuckEmail");

Add the S3 bucket for inbound email

When someone replies to the duck's email, SES deposits the raw message into this bucket. Your Lambda will read it from there.

// --- S3 bucket for inbound email ---
const emailBucket = new sst.aws.Bucket("EmailBucket");

Add the DynamoDB table

We won't use this until Part 2, but let's set it up now so we don't have to redeploy just for a table later. It'll store memories and question history.

// --- DynamoDB table for memories + question history ---
const table = new sst.aws.Dynamo("MemoryTable", {
  fields: {
    pk: "string",
    sk: "string",
  },
  primaryIndex: { hashKey: "pk", rangeKey: "sk" },
});

Add the Ask function

This is the Lambda that generates the daily question. It needs permission to call Bedrock (for Claude) and SES (to send email).

// --- Ask Lambda: generates daily question, sends email ---
const askFn = new sst.aws.Function("AskFn", {
  handler: "src/ask.handler",
  timeout: "30 seconds",
  environment: {
    TABLE_NAME: table.name,
    USER_EMAIL: userEmail.value,
    DUCK_EMAIL: duckEmail.value,
  },
  permissions: [
    {
      actions: ["bedrock:InvokeModel"],
      resources: ["*"],
    },
    {
      actions: ["ses:SendEmail"],
      resources: ["*"],
    },
  ],
  link: [table],
});

The link: [table] gives the function IAM permissions to read/write DynamoDB. We also pass in both email addresses: the human inbox and the duck's SES-backed reply address.

Schedule it

An agent without a schedule is just a function. This cron expression fires at 7:00 AM UTC every day.

// --- Schedule: 7am UTC daily ---
new sst.aws.Cron("DailyAsk", {
  schedule: "cron(0 7 * * ? *)",
  function: askFn.arn,
});

The format is cron(minute hour day-of-month month day-of-week year). The ? means "no specific value" for that field. Adjust the hour to match when you want to hear from your duck — 7 UTC is 3 AM Eastern during daylight time, so choose the UTC hour that matches your local morning.

Add the Listen function

This Lambda processes your email replies. Same permissions as Ask — Bedrock to generate a response and SES to send it — plus access to the email bucket so it can read the raw message SES deposited.

// --- Listen Lambda: processes email replies ---
const listenFn = new sst.aws.Function("ListenFn", {
  handler: "src/listen.handler",
  timeout: "30 seconds",
  environment: {
    TABLE_NAME: table.name,
    USER_EMAIL: userEmail.value,
    DUCK_EMAIL: duckEmail.value,
  },
  permissions: [
    {
      actions: ["bedrock:InvokeModel"],
      resources: ["*"],
    },
    {
      actions: ["ses:SendEmail"],
      resources: ["*"],
    },
  ],
  link: [table, emailBucket],
});

Wire up the S3 trigger

When SES drops a new email into the bucket, this subscription fires the Listen function automatically.

// Subscribe listen function to new objects in the email bucket
emailBucket.subscribe(listenFn, {
  events: ["s3:ObjectCreated:*"],
});

return {
  emailBucketName: emailBucket.name,
  tableName: table.name,
};

The return statement outputs the bucket and table names after deploy, which you'll need for the SES setup.

Verify your personal inbox

Go to the SES console → Verified identities and click Create identity. Choose "Email address," enter the inbox where you want to receive Pip's messages, and click Create.

AWS sends a verification link. Click it. In SES sandbox mode, verified recipients are the only inboxes you can send to.

Verify the duck's address

Pip needs its own address to send from and receive replies on, like pip@duck.yourdomain.com. For this tutorial, verify a dedicated domain or subdomain identity such as duck.yourdomain.com in SES, rather than just the single email address.

SES will ask you to add DNS records for that domain or subdomain. Once they're in place, you can use any address under it as the duck's address. If you already have a real mailbox at the exact duck address, verifying the single address can work for sending, but the subdomain route is the cleaner setup for receiving replies through SES.

Understand sandbox mode

New SES accounts start in sandbox mode. You can only send from verified identities and only send to verified recipient addresses. That's still fine for this tutorial: verify your real inbox as the recipient, and verify the duck subdomain (or exact duck address, if you truly own a mailbox there) as the sender.

If you later want the duck to email unverified recipients, you'd submit a request to move out of the sandbox. But for a personal agent, sandbox mode is enough.

Check your region

SES email receiving is region-specific. This tutorial uses us-east-1, so make sure your SES console, SST config, Bedrock model access, and inbound MX endpoint are all using us-east-1. If you intentionally choose a different SES receiving region, use the matching inbound endpoint from the AWS SES endpoints table.

Point the duck subdomain at SES

The duck address needs to receive replies through SES, which means its domain or subdomain needs an MX record pointing at SES inbound.

For a subdomain like duck.yourdomain.com, add an MX record pointing to inbound-smtp.us-east-1.amazonaws.com with priority 10. Leave your normal inbox domain alone; the whole point is that the duck gets its own lane.

Create a receipt rule set

Go to SES → Email Receiving. If you don't have an active rule set, create one:

1. Click Create rule set
2. Give it a name (e.g., pip-agent-rules)
3. After creating it, click Set as active

An active rule set tells SES to actually process inbound email rules. Without it, nothing happens.

Wait to create the receipt rule

The rule itself needs the S3 bucket that SST creates, so don't create it yet. Finish the code, deploy once, note the emailBucketName output, and then come back to SES to add the rule.

src/lib/bedrock.ts — Talk to Claude

This wraps the Bedrock Runtime client. The askClaude function takes a system prompt and a user message, sends them to Claude Haiku via the Messages API, and returns the text response.

import {
  BedrockRuntimeClient,
  InvokeModelCommand,
} from "@aws-sdk/client-bedrock-runtime";

const client = new BedrockRuntimeClient({});

const MODEL_ID = "anthropic.claude-3-haiku-20240307-v1:0";

interface BedrockResponse {
  content: Array<{ type: string; text: string }>;
}

/**
 * Send a prompt to Claude via Bedrock and return the text response.
 */
export async function askClaude(
  system: string,
  userMessage: string
): Promise<string> {
  const response = await client.send(
    new InvokeModelCommand({
      modelId: MODEL_ID,
      contentType: "application/json",
      accept: "application/json",
      body: JSON.stringify({
        anthropic_version: "bedrock-2023-05-31",
        max_tokens: 1024,
        system,
        messages: [{ role: "user", content: userMessage }],
      }),
    })
  );

  const body: BedrockResponse = JSON.parse(
    new TextDecoder().decode(response.body)
  );
  return body.content[0].text;
}

Bedrock's InvokeModel API expects a raw JSON body — it's not as ergonomic as the Anthropic SDK, but it means no API keys. Your Lambda's IAM role handles authentication automatically.

src/lib/email.ts — Send email

A minimal wrapper around SES SendEmailCommand. Nothing fancy.

import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";

const ses = new SESClient({});

interface SendEmailParams {
  to: string;
  from: string;
  replyTo?: string;
  subject: string;
  body: string;
}

export async function sendEmail({
  to,
  from,
  replyTo,
  subject,
  body,
}: SendEmailParams): Promise<void> {
  await ses.send(
    new SendEmailCommand({
      Destination: { ToAddresses: [to] },
      Source: from,
      ReplyToAddresses: replyTo ? [replyTo] : undefined,
      Message: {
        Subject: { Data: subject },
        Body: {
          Text: { Data: body },
        },
      },
    })
  );
}

src/lib/parse-email.ts — Read replies

Email under the hood is MIME — a format that predates the web and looks like it. The mailparser library does the hard work of turning raw MIME into something readable. We strip quoted lines (starting with >) and "On ... wrote:" attribution lines to get just the new reply content.

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { simpleParser } from "mailparser";

const s3 = new S3Client({});

interface ParsedReply {
  from: string;
  subject: string;
  body: string;
}

/**
 * Fetch a raw email from S3 and parse out the reply body.
 * Strips quoted text (lines starting with ">") to get just the new content.
 */
export async function parseEmailFromS3(
  bucket: string,
  key: string
): Promise<ParsedReply> {
  const response = await s3.send(
    new GetObjectCommand({ Bucket: bucket, Key: key })
  );

  const rawEmail = await response.Body!.transformToString();
  const parsed = await simpleParser(rawEmail);

  // Get the plain text body, strip quoted reply lines
  const fullBody = parsed.text || "";
  const replyOnly = fullBody
    .split("\n")
    .filter((line) => !line.startsWith(">"))
    .join("\n")
    .replace(/On .+ wrote:/g, "") // Remove "On <date> <person> wrote:" lines
    .trim();

  return {
    from: parsed.from?.text || "unknown",
    subject: parsed.subject || "no subject",
    body: replyOnly,
  };
}

This is a good-enough parser. Some email clients format quoted text differently, and you might occasionally get artifacts. For a personal agent that only processes your own replies, it works well.

Set the secrets

Tell SST both addresses: your real inbox and the duck's SES-backed reply address. SST stores them encrypted in your AWS account and injects them into the linked functions.

npx sst secret set UserEmail you@example.com --stage dev
npx sst secret set DuckEmail pip@duck.yourdomain.com --stage dev

Replace you@example.com with the inbox where you want to read Pip's mail. Replace pip@duck.yourdomain.com with the SES-backed duck address you configured above.

Deploy

npx sst deploy --stage dev

This takes a minute or two on the first deploy. SST is creating your S3 bucket, DynamoDB table, Lambda functions, IAM roles, EventBridge schedule, and all the wiring between them. Watch the output — it'll print the bucket name and table name when it finishes.

Note your outputs

After deploy, you'll see something like:

emailBucketName: pip-agent-dev-emailbucket-a1b2c3d4
tableName: pip-agent-dev-memorytable-e5f6g7h8

You'll need the bucket name for the SES receipt rule. The table name is there for Part 2.

Create the receipt rule

Now that the bucket exists, go back to your active SES rule set and click Create rule. Configure it like this:

1. Recipient condition: Add the duck address, like pip@duck.yourdomain.com. This means the rule only fires when mail arrives for Pip.
2. Actions: Add an action of type Deliver to S3 bucket. Select the bucket from the deploy output — the emailBucketName value, named something like pip-agent-dev-emailbucket-xxxxx.
3. Save the rule.

Now when you reply to Pip, the message goes to the duck address, SES catches it, drops the raw message into S3, and S3 triggers your Listen function.

Test the Ask function

Don't wait until tomorrow morning. Invoke the function manually via the AWS CLI:

aws lambda invoke \
  --region us-east-1 \
  --function-name $(aws lambda list-functions \
    --region us-east-1 \
    --query "Functions[?contains(FunctionName, 'pip-agent-dev-AskFn')].FunctionName | [0]" \
    --output text) \
  --cli-binary-format raw-in-base64-out \
  --payload '{}' \
  /dev/stdout

Or find the function in the Lambda console — it'll be named something like pip-agent-dev-AskFn-xxxxx — and click Test with an empty event.

Check your inbox

You should have an email from your duck. The subject line will be "Your duck has a question" and the body will be a single, thoughtful question generated by Claude.

If you don't see it, check your spam folder. SES emails from sandbox accounts sometimes get flagged.

Reply to the duck

Just hit reply like you would for any normal email. Your mail client sends the reply back to the duck address, SES catches it, and the Listen Lambda takes over.

Wait for the acknowledgment

Give it 10-30 seconds. Your reply goes to the duck address, SES deposits it in S3, the Listen Lambda fires, Claude writes a response, and that response lands back in your inbox.

If it doesn't arrive, check CloudWatch Logs. Find the log group for your Listen function (it'll be named /aws/lambda/pip-agent-dev-ListenFn-xxxxx). Common issues:

• No logs at all: The SES receipt rule isn't triggering. Double-check that the rule set is active and the recipient condition matches your duck email.
• S3 access denied before the Lambda starts: The receipt rule's S3 action needs permission to write to the bucket. SES usually prompts you to add a bucket policy during setup.
• S3 access denied inside the Listen logs: The Listen function needs the email bucket in its link list: link: [table, emailBucket].
• Bedrock access denied: Make sure you've enabled Claude Haiku in the Bedrock model access page for your region.