> ## 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.

<Info>**Available now.** Email ships with Identity, on Vetta's own **email layer**, gated by the [policy](/docs/concepts/policies) layer. Inbound mail is verified and stored; the [wake](/docs/identity/inbound) is coming soon.</Info>

An identity can own one or more real **inboxes**. An inbox lives on a verified [web domain](/docs/identity/domains), 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](/docs/identity/domains#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 Vetta 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.
</Tip>

## Addresses: auto vs. manual localparts

<Tabs>
  <Tab title="Auto-provisioned">
    When Vetta 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>

  <Tab title="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
    ```
  </Tab>
</Tabs>

## Provision an inbox

<Steps>
  <Step title="Ensure a verified domain">
    ```bash CLI theme={"system"}
    vetta identity domain list        # need status: active (+ provisioned to send)
    ```
  </Step>

  <Step title="Create the inbox">
    <CodeGroup>
      ```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" }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Send and receive">
    Sending is gated on domain verification and is **credit-checked**; inbound mail wakes the owning agent.
  </Step>
</Steps>

## Sending mail

The agent sends through a `send_email` [tool](/docs/capabilities/tools) bound to the identity. Every send is **credit-checked** against your [budget](/docs/concepts/budgets) and gated on the domain's `dns_status: provisioned`.

<CodeGroup>
  ```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.",
  });
  ```
</CodeGroup>

<Warning>
  A send issued before the domain finishes verifying returns a **retryable** `job_not_ready` rather than a hard error — the [durable runtime](/docs/concepts/runtime) can retry once the domain is `provisioned`.
</Warning>

## Receiving mail

Inbound email flows through Vetta's email layer and becomes an **agent wake**:

<Steps>
  <Step title="Arrive via webhook">
    The email layer delivers the message to Vetta's inbound [webhook](/docs/capabilities/webhooks).
  </Step>

  <Step title="Match to an inbox">
    Vetta matches the recipient to an **active inbox by exact address**. No match → the message is not routed.
  </Step>

  <Step title="Store and wake">
    The message is stored, and the owning agent's alarm is set. A sleeping agent **wakes** through the [durable runtime](/docs/concepts/runtime), reads the mail in one turn, acts, commits, and sleeps.
  </Step>
</Steps>

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

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

<Card title="Next: phone" icon="phone" href="/docs/identity/phone">
  Provision a number and send SMS over carrier-registered messaging.
</Card>