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

# Agent Identity & Account Verification

> Give your agent an address it can sign up with — and let Gorkmail extract OTPs and magic links so it finishes the job.

# Give your AI agent an identity on the internet

Autonomous agents hit a wall the moment a website asks for an email address: agents can't check a human inbox. Gorkmail closes that loop. Your agent gets a real address it controls, and when a service sends a verification email, Gorkmail detects the OTP or magic link and delivers it as structured data — via webhook or a single API call.

```text theme={null}
Agent signs up on a service
        ↓
Service sends verification email
        ↓
Gorkmail receives + sanitizes + detects
        ↓
OTP / magic link delivered as structured data
        ↓
Agent completes signup — human never touches it
```

<CardGroup cols={2}>
  <Card title="Real Address" icon="at">
    Every agent gets an address under `@try.gork.email` (or your verified custom domain) that can send, receive, and maintain conversations.
  </Card>

  <Card title="Verification Intelligence" icon="shield-halved">
    OTP codes and magic links are extracted from inbound mail after Agent Shield sanitization — cloaked or spoofed codes can't poison the result.
  </Card>

  <Card title="Instant Webhooks" icon="bolt">
    `email.verification_detected` fires the moment a verification email lands, HMAC-signed, with retries.
  </Card>

  <Card title="One API Call" icon="code">
    `GET /v1/messages/:id/verification` returns the code, link, expiry, and provider hint — no email parsing in your agent.
  </Card>
</CardGroup>

## Step 1: Provision the agent identity

```typescript TypeScript theme={null}
import { GorkClient } from "@gork/sdk"

const client = new GorkClient({ apiKey: process.env.GORK_API_KEY })

const inbox = await client.inboxes.create({
  username: "signup-bot",
  name: "Account Signup Agent",
})

console.log(inbox.address)
// → signup-bot@try.gork.email
```

Your agent uses this address wherever a signup form asks for email.

## Step 2: Subscribe to verification events

Register a webhook for the `email.verification_detected` event:

```bash cURL theme={null}
curl -X POST https://api.gork.email/v1/webhooks \
  -H "Authorization: Bearer gork_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.com/api/webhooks/gork",
    "subscribedEvents": ["email.verification_detected"]
  }'
```

The payload includes the full signal plus the agent Shield security analysis:

```json theme={null}
{
  "event": "email.verification_detected",
  "message": {
    "id": "msg_908123acdf",
    "inboxId": "inb_89a0b12",
    "threadId": "thd_128bca90f4",
    "from": { "address": "noreply@github.com", "name": "GitHub" },
    "subject": "[GitHub] Please verify your device",
    "receivedAt": "2026-09-08T12:34:56.789Z"
  },
  "verification": {
    "type": "otp",
    "confidence": "high",
    "otp": {
      "code": "728491",
      "expiresAt": "2026-09-08T13:04:56.789Z",
      "providerHint": "github.com"
    },
    "evidence": {
      "subject": "[GitHub] Please verify your device",
      "keyword": "verification code"
    }
  },
  "security": {
    "riskScore": 0,
    "riskLevel": "clean",
    "flags": []
  }
}
```

## Step 3: Complete the signup

Handle the webhook (verify the `X-Gork-Signature` HMAC header first — see the [HMAC guide](/security/hmac)), then hand the code to your browser agent:

```typescript TypeScript theme={null}
export async function POST(req: Request) {
  const rawBody = await req.text()
  // 1. Verify the HMAC-SHA256 signature (see /security/hmac)
  if (!verifySignature(rawBody, req.headers.get("X-Gork-Signature"))) {
    return new Response("Unauthorized", { status: 401 })
  }

  const event = JSON.parse(rawBody)
  if (event.event === "email.verification_detected") {
    const code = event.verification.otp?.code
    const link = event.verification.magicLink?.url

    // 2. Feed the code to your browser agent / automation
    //    and finish the signup flow.
    await completeSignup({ code, link })
  }

  return new Response("OK", { status: 200 })
}
```

## MCP: verification as a native agent tool

Agents running through Claude Desktop, Claude Code, or Cursor get verification as a first-class tool:

```json theme={null}
{
  "mcpServers": {
    "gork": {
      "command": "npx",
      "args": ["-y", "@gork/mcp-server", "--api-key=gork_live_YOUR_KEY"]
    }
  }
}
```

Then prompt your agent:

> "Create an inbox for `signup-bot`, register an account on example.com using that address, then use `gork_get_verification` to get the code and finish the signup."

## Fallback: poll the API

If webhooks aren't an option, your agent can poll:

```typescript TypeScript theme={null}
const messages = await client.messages.list({ inboxId: inbox.id })
const latest = messages[0]
const verification = await client.messages.getVerification(latest.id)
console.log(verification.otp?.code) // → "728491"
```

<Tip>
  Combine verification events with [Agent Shield](/security/agent-shield) and the [Loop Breaker](/security/loop-breaker): the inbound email is sanitized before your agent ever sees it, and runaway auto-reply storms are suppressed server-side.
</Tip>