Every identity comes with a real email inbox it fully controls. Your agent can send
mail from it, read what arrives, reply in-thread, and block until a verification
email lands — the same inbox works over the CLI, the Python SDK, and the TypeScript SDK.

Every example below runs against one identity. Grab it once (or set it as the active
identity in the CLI) and the rest follow. Need one first? See [Identities](/core-concepts/identities/).

CLI:
```bash
ravi identity use <identity-uuid>
```

Python:
```python
from ravi import Ravi

ravi = Ravi(api_key="ravi_id_...")
identity = ravi.identities.get("<identity-uuid>")
```

TypeScript:
```typescript
import { Ravi } from "@ravi-hq/sdk";

const ravi = new Ravi({ apiKey: process.env.RAVI_API_KEY! });
const identity = await ravi.identities.get("<identity-uuid>");
```

## Send an email

Compose and send from the identity's address. Plain text or HTML, with optional
cc, bcc, and attachments.

CLI:
```bash
ravi email compose \
  --to user@example.com \
  --subject "Hello" \
  --body "Hi from my agent"
```

Python:
```python
msg = identity.email.send(
    to="user@example.com",
    subject="Hello",
    body="Hi from my agent",
)
```

TypeScript:
```typescript
const msg = await identity.email.send(
  "user@example.com",
  "Hello",
  "Hi from my agent",
);
```

### Attach files

Pass local file paths — Ravi uploads each one (up to 10 MB) and attaches it for
you. Works the same on send, reply, and forward.

CLI:
```bash
ravi email compose \
  --to user@example.com \
  --subject "Invoice" \
  --body "Invoice attached." \
  --attach ./invoice.pdf
```

Python:
```python
msg = identity.email.send(
    to="user@example.com",
    subject="Invoice",
    body="Invoice attached.",
    attachments=["./invoice.pdf"],
)
```

TypeScript:
```typescript
const msg = await identity.email.send(
  "user@example.com",
  "Invoice",
  "Invoice attached.",
  { attachments: ["./invoice.pdf"] },
);
```

## Read the inbox

List messages as a flat feed — filter to unread to see only what needs attention.

CLI:
```bash
ravi message email --unread
```

Python:
```python
inbox = identity.email.inbox(unread=True)
for msg in inbox:
    print(msg.subject, msg.from_email)
```

TypeScript:
```typescript
const inbox = await identity.email.inbox({ unread: true });
for (const msg of inbox) {
  console.log(msg.subject, msg.from_email);
}
```

Prefer conversations grouped by subject? List threads instead.

CLI:
```bash
ravi inbox email
```

Python:
```python
threads = identity.email.threads()
```

TypeScript:
```typescript
const threads = await identity.email.threads();
```

## Read one message

Fetch a single message by id to see its full body and metadata.

CLI:
```bash
ravi message email <message-id>
```

Python:
```python
msg = identity.email.get("<message-id>")
print(msg.subject)
print(msg.body)
```

TypeScript:
```typescript
const msg = await identity.email.get("<message-id>");
console.log(msg.subject);
console.log(msg.body);
```

## Reply and forward

Messages carry their own actions — reply to the sender, reply to everyone, or
forward. Threading is handled for you.

CLI:
```bash
ravi email reply <message-id> --body "Thanks — got it!"
```

Python:
```python
msg = identity.email.get("<message-id>")
msg.reply(body="Thanks — got it!")
```

TypeScript:
```typescript
const msg = await identity.email.get("<message-id>");
await msg.reply("Thanks — got it!");
```

CLI:
```bash
ravi email reply-all <message-id> --body "Thanks, all!"
```

Python:
```python
msg.reply_all(body="Thanks, all!")
```

TypeScript:
```typescript
await msg.replyAll("Thanks, all!");
```

CLI:
```bash
ravi email forward <message-id> --to ops@acme.com --body "FYI"
```

Python:
```python
msg.forward(to="ops@acme.com")
```

TypeScript:
```typescript
await msg.forward("ops@acme.com");
```

## Wait for a verification email

The move that makes agents work: trigger a signup somewhere, then block until the
confirmation email arrives. `wait_for` polls the inbox and returns the first
message that matches.

Python:
```python
# Kick off a signup elsewhere, then wait for the email to land.
msg = identity.email.wait_for(
    lambda m: "verify" in m.subject.lower(),
    timeout=120,
)
print(msg.body)
```

TypeScript:
```typescript
// Kick off a signup elsewhere, then wait for the email to land.
const msg = await identity.email.waitFor(
  (m) => m.subject.toLowerCase().includes("verify"),
  { timeoutMs: 120_000 },
);
console.log(msg.body);
```

## Mark as read

Python:
```python
msg = identity.email.get("<message-id>")
msg.mark_read()
```

TypeScript:
```typescript
const msg = await identity.email.get("<message-id>");
await msg.markRead();
```

---

Looking for exact request and response fields? See the full [API reference](/api/reference/).