> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Provision inboxes on a verified domain; send credit-checked mail and wake the agent on inbound.

> [!NOTE]
>
> **Available now.** Email ships with Identity, on Naive Managed Agents' own **email layer**, gated by the [policy](https://vetta.sh/docs/concepts/policies.md) layer. Inbound mail is verified, stored and [wakes the inbox's agent](https://vetta.sh/docs/identity/inbound.md).

An identity can own one or more real **inboxes**. An inbox lives on a verified [web domain](https://vetta.sh/docs/identity/domains.md), and its address is simply `localpart@domain` — e.g. `ava@acme-mail.com`. Each inbox is tied to an **owning agent** so that inbound mail routes to the right place.

## The domain comes first

Inboxes cannot exist on an unverified domain. The rules come straight from the [domain readiness gate](https://vetta.sh/docs/identity/domains.md#the-email-readiness-gate):

| Action | Requires |
| - | - |
| Create an inbox | domain `status: active` |
| **Send** | domain `dns_status: provisioned` |
| **Receive** | domain verified for inbound at the email layer |

> [!TIP]
>
> At signup Managed Agents auto-provisions a `system` domain (`{org-slug}.<vetta-apex>`) that is already sending- and receiving-ready, so you can create an inbox immediately without touching a registrar.

## Addresses: auto vs. manual localparts

> [tab] Auto-provisioned
>
> When Managed Agents provisions an inbox for an agent, the localpart is derived from the **agent name**: slugified, truncated to **≤ 32 chars**, and given a collision suffix if the address is already taken.
>
> ```
> agent "Ava Sales"  →  ava-sales@acme-mail.com
> (collision)        →  ava-sales-2@acme-mail.com
> ```

> [tab] Manual
>
> When you choose the address, the localpart must match `[a-z0-9._-]` and be **at least 2 characters**.
>
> ```bash CLI theme={"system"}
> vetta identity email provision --identity ava --address ava@acme-mail.com
> ```

## Provision an inbox

**1. Ensure a verified domain**

```bash CLI theme={"system"}
vetta identity domain list        # need status: active (+ provisioned to send)
```

**2. Create the inbox**

```bash CLI theme={"system"}
vetta identity email provision --identity ava --address ava@acme-mail.com
```

```typescript TypeScript theme={"system"}
const inbox = await vetta.emails.create(identity.id, {
  address: "ava@acme-mail.com",
});
```

```bash cURL theme={"system"}
curl https://api.vetta.sh/v1/identities/$IDN/emails \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "address": "ava@acme-mail.com" }'
```

**3. Send and receive**

Sending is gated on domain verification and is **credit-checked**; inbound mail wakes the owning agent.

## Sending mail

The agent reads its inboxes with `email.inboxes` / `email.read` and sends through `email.send`, [tools](https://vetta.sh/docs/capabilities/tools.md#email-tools) bound to the session's identity; `email.send` asks for approval by default. Every send is **credit-checked** against your [budget](https://vetta.sh/docs/concepts/budgets.md) and gated on the domain's `dns_status: provisioned`.

```bash CLI theme={"system"}
vetta identity email send --identity ava \
  --to customer@example.com \
  --subject "Your refund" \
  --text "We've processed your refund for order #4821."
```

```typescript TypeScript theme={"system"}
// The inbox is addressed by id, not by its `from` address: one identity can hold several.
await vetta.emails.send(identity.id, inbox.id, {
  to: ["customer@example.com"],
  subject: "Your refund",
  text: "We've processed your refund for order #4821.",
});
```

> [!WARNING]
>
> A send issued before the domain finishes verifying returns a **retryable** `job_not_ready` rather than a hard error — the [durable runtime](https://vetta.sh/docs/concepts/runtime.md) can retry once the domain is `provisioned`.

## Receiving mail

Inbound email flows through Managed Agents' email layer and becomes an **agent wake**:

**1. Arrive via webhook**

The email layer delivers the message to Managed Agents' inbound [webhook](https://vetta.sh/docs/capabilities/webhooks.md).

**2. Match to an inbox**

Managed Agents matches the recipient to an **active inbox by exact address**. No match → the message is not routed.

**3. Store and wake**

The message is stored and, unless a [guard](https://vetta.sh/docs/identity/inbound.md#safety-inbound-is-untrusted) holds it, starts a session for the inbox's owning agent as this persona (the agent must hold it). The agent reads the mail, may answer with `email.send` from this inbox, commits, and sleeps.

```bash CLI theme={"system"}
vetta identity email list --identity ava     # inboxes + recent messages
```

See [Inbound](https://vetta.sh/docs/identity/inbound.md) for the full wake-handle-sleep path shared by email, SMS, and connection events.

> [card] [Next: phone](https://vetta.sh/docs/identity/phone.md)
>
> Provision a number and send SMS over carrier-registered messaging.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.