Quickstart

Get your agent up and running with a real email address in under 5 minutes.

In this guide, you will:

1. Obtain an API Key from the Wirebox Console.
2. Claim a dedicated agent identity and mailbox (@eva).
3. Send an email to the agent and observe the incoming thread.
4. Reply to the conversation using the API.

---

Step 1: Get an API Key

1. Open the Wirebox Console.
2. Sign in with GitHub or Google.
3. Navigate to API Keys and click Create Key.
4. Save the generated key (wb_live_...).

Export your key in your terminal:

export WIREBOX_API_KEY="wb_live_your_secret_key_here"

---

Step 2: Create an Agent Identity

Claim a handle for your agent. When you create an identity, Wirebox automatically creates its mailbox ([e-mail]).

cURL

curl -X POST https://api.wirebox.sh/api/v1/identities \
  -H "Authorization: Bearer $WIREBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_handle": "eva",
    "display_name": "Eva Support Agent",
    "description": "Autonomous customer triage agent"
  }'

Response (201 Created):

{
  "id": "ident_01J8ABC123XYZ",
  "agent_handle": "eva",
  "display_name": "Eva Support Agent",
  "description": "Autonomous customer triage agent",
  "mailbox_address": "[e-mail]",
  "created_at": "2026-09-11T10:00:00Z",
  "updated_at": "2026-09-11T10:00:00Z"
}

---

Step 3: Receive an Email

Send an email from your personal Gmail or Outlook account to [e-mail].

Wirebox’s edge routing engine immediately:

1. Ingests the raw MIME message.
2. Extracts plain text and HTML bodies, headers, and attachments.
3. Groups the message into an active conversation Thread.
4. Fires a message.received webhook if configured.

List incoming threads for your agent:

cURL

curl -X GET "https://api.wirebox.sh/api/v1/mail/threads?agent=eva" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

---

Step 4: Send a Reply

Reply to the sender using the thread’s ID or conversation context:

cURL

curl -X POST https://api.wirebox.sh/api/v1/mail/send \
  -H "Authorization: Bearer $WIREBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "eva",
    "to": ["[e-mail]"],
    "subject": "Re: Help with account setup",
    "text": "Hello! I am Eva, your AI support assistant. I received your message and have resolved the issue.",
    "thread_id": "thrd_01J8XYZ987ABC"
  }'

Congratulations! You have set up a full-duplex email workflow for your AI agent.

---

Next Steps

• Set up Webhooks to receive real-time notifications on your server whenever a new email arrives.
• Explore the API Reference to inspect all available query filters and endpoints.