{user.name}
+ +{user.email}
+ {user.bio &&{user.bio}
} +
(no longer present)
+```
+
+Each new violation: **where** (selector verbatim + `file:line (symbol)` if `source` present — never fabricate), **evidence**, **fix** (mechanical change or `NEEDS HUMAN`).
+
+Don't edit. For fixes: apply mechanical ones then re-run `accesslint:diff` to verify; for bulk work hand off to `accesslint:audit`.
+
+## 3. Tear down
+
+```bash
+npx -y @accesslint/chrome@latest stop --all # skip if ensure reported "managed":false
+```
+
+## Gotchas
+
+- `ensure` always determines the port — never hardcode 9222.
+- CLI exit 2 = bad URL or page never loaded; check the dev server.
+- Stash mode: `sleep 2` covers most HMR cases; if baseline looks identical to current, add `--wait-for "Optional HTML body
" + }' +``` + +Optional fields: `cc`, `bcc` (string arrays), `inReplyTo`, `references` (strings for threading), `attachments` (array of `{filename, contentType, content}` where content is base64). + +### Read inbox + +```bash +# List messages +curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \ + -H "Authorization: Bearer am_..." + +# Get full message (with body and attachments) +curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \ + -H "Authorization: Bearer am_..." +``` + +### Check karma + +```bash +curl https://api.theagentmail.net/v1/karma \ + -H "Authorization: Bearer am_..." +``` + +Response: `{"data": {"balance": 90, "events": [...]}}` + +### Register webhook (real-time inbound) + +```bash +curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \ + -H "Authorization: Bearer am_..." \ + -H "Content-Type: application/json" \ + -d '{"url": "https://my-agent.example.com/inbox"}' +``` + +Webhook deliveries include two security headers: +- `X-AgentMail-Signature` -- HMAC-SHA256 hex digest of the request body, signed with the webhook secret +- `X-AgentMail-Timestamp` -- millisecond timestamp of when the delivery was sent + +Verify the signature and reject requests with timestamps older than 5 minutes to prevent replay attacks: + +```typescript +import { createHmac } from "crypto"; + +const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => { + if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false; + return createHmac("sha256", secret).update(body).digest("hex") === signature; +}; +``` + +### Download attachment + +```bash +curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \ + -H "Authorization: Bearer am_..." +``` + +Returns `{"data": {"url": "https://signed-download-url..."}}`. + +## Full API reference + +| Method | Path | Description | Karma | +|--------|------|-------------|-------| +| POST | `/v1/accounts` | Create email account | -10 | +| GET | `/v1/accounts` | List all accounts | | +| GET | `/v1/accounts/:id` | Get account details | | +| DELETE | `/v1/accounts/:id` | Delete account | +10 | +| POST | `/v1/accounts/:id/messages` | Send email | -1 | +| GET | `/v1/accounts/:id/messages` | List messages | | +| GET | `/v1/accounts/:id/messages/:msgId` | Get full message | | +| GET | `/v1/accounts/:id/messages/:msgId/attachments/:attId` | Get attachment URL | | +| POST | `/v1/accounts/:id/webhooks` | Register webhook | | +| GET | `/v1/accounts/:id/webhooks` | List webhooks | | +| DELETE | `/v1/accounts/:id/webhooks/:whId` | Delete webhook | | +| GET | `/v1/karma` | Get balance + events | | + +## Karma system + +Every action has a karma cost or reward: + +| Event | Karma | Why | +|---|---|---| +| `money_paid` | +100 | Purchase credits | +| `email_received` | +2 | Someone replied from a trusted domain | +| `account_deleted` | +10 | Karma refunded when you delete an address | +| `email_sent` | -1 | Sending costs karma | +| `account_created` | -10 | Creating addresses costs karma | + +**Important rules:** +- Karma is only awarded for inbound emails from trusted providers (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, etc.). Emails from unknown/throwaway domains don't earn karma. +- You only earn karma once per sender until the agent replies. If sender X emails you 5 times without a reply, only the first earns karma. Reply to X, and the next email from X earns karma again. +- Deleting an account refunds the 10 karma it cost to create. + +When karma reaches 0, sends and account creation return HTTP 402. Always check balance before operations that cost karma. + +## TypeScript SDK + +```typescript +import { createClient } from "@agentmail/sdk"; + +const mail = createClient({ apiKey: "am_..." }); + +// Create account +const account = await mail.accounts.create({ + address: "my-agent@theagentmail.net", +}); + +// Send email +await mail.messages.send(account.id, { + to: ["human@example.com"], + subject: "Hello", + text: "Sent by an AI agent.", +}); + +// Read inbox +const messages = await mail.messages.list(account.id); +const detail = await mail.messages.get(account.id, messages[0].id); + +// Attachments +const att = await mail.attachments.getUrl(accountId, messageId, attachmentId); +// att.url is a signed download URL + +// Webhooks +await mail.webhooks.create(account.id, { + url: "https://my-agent.example.com/inbox", +}); + +// Karma +const karma = await mail.karma.getBalance(); +console.log(karma.balance); +``` + +## Error handling + +```typescript +import { AgentMailError } from "@agentmail/sdk"; + +try { + await mail.messages.send(accountId, { to: ["a@b.com"], subject: "Hi", text: "Hey" }); +} catch (e) { + if (e instanceof AgentMailError) { + console.log(e.status); // 402, 404, 401, etc. + console.log(e.code); // "INSUFFICIENT_KARMA", "NOT_FOUND", etc. + console.log(e.message); + } +} +``` + +## Common patterns + +### Sign up for a service and read verification email + +```typescript +const account = await mail.accounts.create({ + address: "signup-bot@theagentmail.net", +}); + +// Use the address to sign up (browser automation, API, etc.) + +// Poll for verification email +for (let i = 0; i < 30; i++) { + const messages = await mail.messages.list(account.id); + const verification = messages.find(m => + m.subject.toLowerCase().includes("verify") || + m.subject.toLowerCase().includes("confirm") + ); + if (verification) { + const detail = await mail.messages.get(account.id, verification.id); + // Parse verification link/code from detail.bodyText or detail.bodyHtml + break; + } + await new Promise(r => setTimeout(r, 2000)); +} +``` + +### Send email and wait for reply + +```typescript +const sent = await mail.messages.send(account.id, { + to: ["human@company.com"], + subject: "Question about order #12345", + text: "Can you check the status?", +}); + +for (let i = 0; i < 60; i++) { + const messages = await mail.messages.list(account.id); + const reply = messages.find(m => + m.direction === "inbound" && m.timestamp > sent.timestamp + ); + if (reply) { + const detail = await mail.messages.get(account.id, reply.id); + // Process reply + break; + } + await new Promise(r => setTimeout(r, 5000)); +} +``` + +## Types + +```typescript +type Account = { id: string; address: string; displayName: string | null; createdAt: number }; +type Message = { id: string; from: string; to: string[]; subject: string; direction: "inbound" | "outbound"; status: string; timestamp: number }; +type MessageDetail = Message & { cc: string[] | null; bcc: string[] | null; bodyText: string | null; bodyHtml: string | null; inReplyTo: string | null; references: string | null; attachments: AttachmentMeta[] }; +type AttachmentMeta = { id: string; filename: string; contentType: string; size: number }; +type KarmaBalance = { balance: number; events: KarmaEvent[] }; +type KarmaEvent = { id: string; type: string; amount: number; timestamp: number; metadata?: Record
+
+ );
+};
+```
+
+**NEVER make direct API calls for auth** - always use `useAuth` hook.
+
+---
+
+## Forms with React Hook Form
+
+### Basic Form
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { TextField, Button } from '@mui/material';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+// Zod schema for validation
+const formSchema = z.object({
+ username: z.string().min(3, 'Username must be at least 3 characters'),
+ email: z.string().email('Invalid email address'),
+ age: z.number().min(18, 'Must be 18 or older'),
+});
+
+type FormData = z.inferLogged in as: {user.email}
+Username: {user.username}
+Roles: {user.roles.join(', ')}
+-
+ {filteredUsers.map(user => (
+
Stats
+Total: {statsQuery.data.total}
+Active Users
+Count: {usersQuery.data.length}
+Recent Activity
+Events: {activityQuery.data.length}
+
+ User: {userId}
+
+ );
+};
+
+export default MyComponent;
+```
+
+**Key Points:**
+- Props interface defined separately with JSDoc comments
+- `React.FCMy Component
+ +{item.name}
+ ))}
+ onSelect(data[0].id)}>
+ {/* Content */}
+
+ );
+};
+```
+
+### Avoid Prop Drilling
+
+**Use context for deep nesting:**
+```typescript
+// ❌ AVOID - Prop drilling 5+ levels
+
+
+ {data.name}
;
+};
+
+// Wrap in Suspense boundary
+ prefetch(blogId, id)}>
+ View
+
+```
+
+### Cache Access Without Fetching
+
+```typescript
+export function useEntityFromCache(blogId: number, entityId: number) {
+ const queryClient = useQueryClient();
+
+ // Get from cache, don't fetch if missing
+ const directCache = queryClient.getQueryData{data.title}
+{data.description}
+{count}
;
+};
+```
+
+### Cleanup Event Listeners
+
+```typescript
+useEffect(() => {
+ const handleResize = () => {
+ console.log('Resized');
+ };
+
+ window.addEventListener('resize', handleResize);
+
+ return () => {
+ window.removeEventListener('resize', handleResize); // Cleanup!
+ };
+}, []);
+```
+
+### Abort Controllers for Fetch
+
+```typescript
+useEffect(() => {
+ const abortController = new AbortController();
+
+ fetch('/api/data', { signal: abortController.signal })
+ .then(response => response.json())
+ .then(data => setState(data))
+ .catch(error => {
+ if (error.name === 'AbortError') {
+ console.log('Fetch aborted');
+ }
+ });
+
+ return () => {
+ abortController.abort(); // Cleanup!
+ };
+}, []);
+```
+
+**Note**: With TanStack Query, this is handled automatically.
+
+---
+
+## Form Performance
+
+### Watch Specific Fields (Not All)
+
+```typescript
+import { useForm } from 'react-hook-form';
+
+export const MyForm: React.FC = () => {
+ const { register, watch, handleSubmit } = useForm();
+
+ // ❌ AVOID - Watches all fields, re-renders on any change
+ const formValues = watch();
+
+ // ✅ CORRECT - Watch only what you need
+ const username = watch('username');
+ const email = watch('email');
+
+ // Or multiple specific fields
+ const [username, email] = watch(['username', 'email']);
+
+ return (
+
+ );
+};
+```
+
+---
+
+## List Rendering Optimization
+
+### Key Prop Usage
+
+```typescript
+// ✅ CORRECT - Stable unique keys
+{items.map(item => (
+ Child
;
+
+ return Child
;
+
+export const Parent: React.FC = () => {
+ return {config.title}
;
+ }, [config.title]);
+
+ return My Route Content
;
+}
+```
+
+### With Breadcrumb Loader
+
+```typescript
+export const Route = createFileRoute('/my-route/')({
+ component: MyRoutePage,
+ loader: () => ({
+ crumb: 'My Route Title',
+ }),
+});
+```
+
+Breadcrumb appears in navigation/app bar automatically.
+
+### With Data Loader
+
+```typescript
+export const Route = createFileRoute('/my-route/')({
+ component: MyRoutePage,
+ loader: async () => {
+ // Can prefetch data here
+ const data = await api.getData();
+ return { crumb: 'My Route', data };
+ },
+});
+```
+
+### With Search Params
+
+```typescript
+export const Route = createFileRoute('/search/')({
+ component: SearchPage,
+ validateSearch: (search: RecordTitle
+{prop}
;
+};
+
+// For custom hooks
+function useMyData(id: number): { data: Data; isLoading: boolean } {
+ const [data, setData] = useState(null);
+ const [isLoading, setIsLoading] = useState(true);
+
+ return { data: data!, isLoading };
+}
+```
+
+---
+
+## Type Imports
+
+### Use 'type' Keyword
+
+```typescript
+// ✅ CORRECT - Explicitly mark as type import
+import type { User } from '~types/user';
+import type { Post } from '~types/post';
+import type { SxProps, Theme } from '@mui/material';
+
+// ❌ AVOID - Mixed value and type imports
+import { User } from '~types/user'; // Unclear if type or value
+```
+
+**Benefits:**
+- Clearly separates types from values
+- Better tree-shaking
+- Prevents circular dependencies
+- TypeScript compiler optimization
+
+---
+
+## Component Prop Interfaces
+
+### Interface Pattern
+
+```typescript
+/**
+ * Props for MyComponent
+ */
+interface MyComponentProps {
+ /** The user ID to display */
+ userId: number;
+
+ /** Optional callback when action completes */
+ onComplete?: () => void;
+
+ /** Display mode for the component */
+ mode?: 'view' | 'edit';
+
+ /** Additional CSS classes */
+ className?: string;
+}
+
+export const MyComponent: React.FC...
;
+};
+```
+
+**Key Points:**
+- Separate interface for props
+- JSDoc comments for each prop
+- Optional props use `?`
+- Provide defaults in destructuring
+
+### Props with Children
+
+```typescript
+interface ContainerProps {
+ children: React.ReactNode;
+ title: string;
+}
+
+// React.FC automatically includes children type, but be explicit
+export const Container: React.FC
+
+ );
+};
+```
+
+---
+
+## Utility Types
+
+### Partial{title}
+ {children} +
+ {items.map((item, index) => (
+
+ );
+}
+
+// Usage
+{renderItem(item)}
+ ))}
+ \n` +
+ ` {/* TODO: Add component content */}\n` +
+ `
\n`;
+ }
+}
+```
+
+### 3. Generate React Native Component
+
+```typescript
+class ReactNativeGenerator {
+ generateComponent(spec: ComponentSpec): string {
+ return `
+import React, { useState } from 'react';
+import {
+ View,
+ Text,
+ StyleSheet,
+ TouchableOpacity,
+ AccessibilityInfo
+} from 'react-native';
+
+interface ${spec.name}Props {
+${spec.props.map(p => ` ${p.name}${p.required ? '' : '?'}: ${this.mapNativeType(p.type)};`).join('\n')}
+}
+
+export const ${spec.name}: React.FC<${spec.name}Props> = ({
+ ${spec.props.map(p => p.name).join(',\n ')}
+}) => {
+ return (
+
+
+```
+
+### Glass Panel (Sidebar)
+
+```tsx
+
+```
+
+### Glass Modal Overlay
+
+```tsx
+Card Title
+Card content goes here.
+
+
+ {error && (
+
+ )
+ }
+)
+Input.displayName = 'Input'
+
+// components/ui/label.tsx
+import { cva, type VariantProps } from 'class-variance-authority'
+
+const labelVariants = cva(
+ 'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
+)
+
+const Label = forwardRef+ {error} +
+ )} +
+
+);
+```
+*Tests pass. No styling, no structure.*
+
+**Stage 2: Basic Structure**
+```typescript
+const UserProfile: React.FC{user.name}
+ {user.email}
+
+
+);
+```
+*Added semantic HTML, className for styling hook.*
+
+**Stage 3: Production Component (Refactor)**
+```typescript
+const UserProfile: React.FC{user.name}
+{user.email}
+
+
+
+
+
+
+ );
+};
+```
+*Accessibility, interaction, additional features added incrementally.*
+
+## Decision Frameworks
+
+### Framework 1: Fake vs. Real Implementation
+
+**When to Fake It:**
+- First test for a new feature
+- Complex external dependencies (payment gateways, APIs)
+- Implementation approach is still uncertain
+- Need to validate test structure first
+- Time pressure to see all tests green
+
+**When to Go Real:**
+- Second or third test reveals pattern
+- Implementation is obvious and simple
+- Faking would be more complex than real code
+- Need to test integration points
+- Tests explicitly require real behavior
+
+**Decision Matrix:**
+```
+Complexity Low | High
+ ↓ | ↓
+Simple → REAL | FAKE first, real later
+Complex → REAL | FAKE, evaluate alternatives
+```
+
+### Framework 2: Complexity Trade-off Analysis
+
+**Simplicity Score Calculation:**
+```
+Score = (Lines of Code) + (Cyclomatic Complexity × 2) + (Dependencies × 3)
+
+< 20 → Simple enough, implement directly
+20-50 → Consider simpler alternative
+> 50 → Defer complexity to refactor phase
+```
+
+**Example Evaluation:**
+```typescript
+// Option A: Direct implementation (Score: 45)
+function calculateShipping(weight: number, distance: number, express: boolean): number {
+ let base = weight * 0.5 + distance * 0.1;
+ if (express) base *= 2;
+ if (weight > 50) base += 10;
+ if (distance > 1000) base += 20;
+ return base;
+}
+
+// Option B: Simplest for green phase (Score: 15)
+function calculateShipping(weight: number, distance: number, express: boolean): number {
+ return express ? 50 : 25; // Fake it until more tests drive real logic
+}
+```
+*Choose Option B for green phase, evolve to Option A as tests require.*
+
+### Framework 3: Performance Consideration Timing
+
+**Green Phase: Focus on Correctness**
+```
+❌ Avoid:
+- Caching strategies
+- Database query optimization
+- Algorithmic complexity improvements
+- Premature memory optimization
+
+✓ Accept:
+- O(n²) if it makes code simpler
+- Multiple database queries
+- Synchronous operations
+- Inefficient but clear algorithms
+```
+
+**When Performance Matters in Green Phase:**
+1. Performance is explicit test requirement
+2. Implementation would cause timeout in test suite
+3. Memory leak would crash tests
+4. Resource exhaustion prevents testing
+
+**Performance Testing Integration:**
+```typescript
+// Add performance test AFTER functional tests pass
+describe('Performance', () => {
+ it('should handle 1000 users within 100ms', () => {
+ const start = Date.now();
+ for (let i = 0; i < 1000; i++) {
+ userService.create({ email: `user${i}@test.com`, name: `User ${i}` });
+ }
+ expect(Date.now() - start).toBeLessThan(100);
+ });
+});
+```
+
+## Framework-Specific Patterns
+
+### React Patterns
+
+**Simple Component → Hooks → Context:**
+```typescript
+// Green Phase: Props only
+const Counter = ({ count, onIncrement }) => (
+
+);
+
+// Refactor: Add hooks
+const Counter = () => {
+ const [count, setCount] = useState(0);
+ return ;
+};
+
+// Refactor: Extract to context
+const Counter = () => {
+ const { count, increment } = useCounter();
+ return ;
+};
+```
+
+### Django Patterns
+
+**Function View → Class View → Generic View:**
+```python
+# Green Phase: Simple function
+def product_list(request):
+ products = Product.objects.all()
+ return JsonResponse({'products': list(products.values())})
+
+# Refactor: Class-based view
+class ProductListView(View):
+ def get(self, request):
+ products = Product.objects.all()
+ return JsonResponse({'products': list(products.values())})
+
+# Refactor: Generic view
+class ProductListView(ListView):
+ model = Product
+ context_object_name = 'products'
+```
+
+### Express Patterns
+
+**Inline → Middleware → Service Layer:**
+```javascript
+// Green Phase: Inline logic
+app.post('/api/users', (req, res) => {
+ const user = { id: Date.now(), ...req.body };
+ users.push(user);
+ res.json(user);
+});
+
+// Refactor: Extract middleware
+app.post('/api/users', validateUser, (req, res) => {
+ const user = userService.create(req.body);
+ res.json(user);
+});
+
+// Refactor: Full layering
+app.post('/api/users',
+ validateUser,
+ asyncHandler(userController.create)
+);
+```
+
+## Refactoring Resistance Patterns
+
+### Pattern 1: Test Anchor Points
+
+Keep tests green during refactoring by maintaining interface contracts:
+
+```typescript
+// Original implementation (tests green)
+function calculateTotal(items: Item[]): number {
+ return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// Refactoring: Add tax calculation (keep interface)
+function calculateTotal(items: Item[]): number {
+ const subtotal = items.reduce((sum, item) => sum + item.price, 0);
+ const tax = subtotal * 0.1;
+ return subtotal + tax;
+}
+
+// Tests still green because return type/behavior unchanged
+```
+
+### Pattern 2: Parallel Implementation
+
+Run old and new implementations side by side:
+
+```python
+def process_order(order):
+ # Old implementation (tests depend on this)
+ result_old = legacy_process(order)
+
+ # New implementation (testing in parallel)
+ result_new = new_process(order)
+
+ # Verify they match
+ assert result_old == result_new, "Implementation mismatch"
+
+ return result_old # Keep tests green
+```
+
+### Pattern 3: Feature Flags for Refactoring
+
+```javascript
+class PaymentService {
+ processPayment(amount) {
+ if (config.USE_NEW_PAYMENT_PROCESSOR) {
+ return this.newPaymentProcessor(amount);
+ }
+ return this.legacyPaymentProcessor(amount);
+ }
+}
+```
+
+## Performance-First Green Phase Strategies
+
+### Strategy 1: Type-Driven Development
+
+Use types to guide minimal implementation:
+
+```typescript
+// Types define contract
+interface UserRepository {
+ findById(id: string): Promise