Cấp cho AI agent một địa chỉ email bằng một lệnh gọi API

Một AI agent có thể đăng ký một dịch vụ, khởi chạy một job hay tạo một ticket hỗ trợ, rồi luồng công việc dừng lại, vì câu trả lời đến một nơi mà agent không hiện diện: một hộp thư email. Mã xác minh, biên nhận, thông báo kiểu “bản export của bạn đã sẵn sàng”, đặt lại mật khẩu. Email là cơ chế callback lâu đời nhất của internet, và agent thì không có địa chỉ.

Bài này trình bày cách khắc phục nhỏ nhất mà chúng tôi có thể xây. Một lệnh gọi API, không cần đăng ký, trả về một địa chỉ email hoạt động thật; thư gửi đến địa chỉ đó trở thành các sự kiện có cấu trúc mà agent đọc lại qua HTTP, trong cùng nhật ký sự kiện nơi các webhook của nó đổ về.

TL;DR

POST https://anyhook.net/api/v1/quickstart (không cần xác thực) trả về một inbox_address dạng q-cd3fe0f8.quickstart@anyhook.net, kèm một inbound_url cho webhook và một API key
Thư gửi tới địa chỉ đó trở thành một sự kiện email.received: from, to, subject, message_id và toàn bộ thông điệp MIME gốc
Agent liệt kê sự kiện bằng GET /api/v1/events và đọc từng sự kiện bằng GET /api/v1/events/{id}, hoặc qua MCP với anyhook_inbox / anyhook_events / anyhook_inspect (registry: net.anyhook/anyhook, endpoint MCP từ xa https://anyhook.net/mcp)
Nó chỉ nhận. Nó không gửi hay trả lời được, và đó là một ranh giới có chủ đích, không phải thứ còn thiếu trong roadmap
Endpoint miễn phí hết hạn sau 7 ngày nếu không được nhận về tài khoản (claim); gói Free giới hạn ở 1.000 sự kiện/ngày

Một lệnh gọi duy nhất

curl -X POST https://anyhook.net/api/v1/quickstart

{
  "inbound_url": "https://in.anyhook.net/q-cd3fe0f8/quickstart",
  "inbox_address": "q-cd3fe0f8.quickstart@anyhook.net",
  "api_key": "ahk_live_…",
  "claim_url": "https://anyhook.net/claim/…",
  "expires_at": "2026-08-06T…"
}

Bạn không phải tạo tài khoản, giải captcha hay bấm qua màn hình đồng ý OAuth. Điều đó quan trọng vì bên gọi ở đây thường không phải con người. Đó là một agent đang làm dở việc, và mỗi form đăng ký trong vòng lặp là một chỗ công việc có thể chết. Endpoint là tạm thời (7 ngày) cho tới khi một người nhận nó về tài khoản qua claim_url, và đó cũng là trần chống lạm dụng: không thứ gì ẩn danh sống lâu hơn TTL của nó.

Cùng một App (một URL nhận cho một nguồn webhook, ví dụ “Stripe production”) giờ nhận trên hai kênh:

Kênh	Địa chỉ
Webhook HTTP	`https://in.anyhook.net/q-cd3fe0f8/quickstart`
Email	`q-cd3fe0f8.quickstart@anyhook.net`

Cả hai cùng đổ vào một nhật ký sự kiện, nên “chờ webhook của Stripe” và “chờ email xác nhận” là cùng một thao tác từ phía agent: polling (định kỳ gọi API để hỏi dữ liệu mới) events API, rồi xem payload.

Một email trở thành gì

Gửi bất kỳ thư nào tới địa chỉ đó. Trong vài giây, nó xuất hiện dưới dạng một sự kiện:

{
  "type": "email.received",
  "from": "noreply@github.com",
  "to": "q-cd3fe0f8.quickstart@anyhook.net",
  "subject": "Your verification code is 481920",
  "message_id": "<abc123@mail.example.com>",
  "date": "Thu, 30 Jul 2026 11:42:31 +0700",
  "size": 7026,
  "raw": "Received: from …"
}

raw là toàn bộ thông điệp MIME, nguyên vẹn không chỉnh sửa: mọi header, mọi phần, mọi tệp đính kèm, đúng như lúc đến. Các trường metadata chỉ để tiện dùng; thông điệp gốc mới là nguồn sự thật. Với trường hợp phổ biến nhất của agent là lấy mã ra từ một email xác minh, chỉ riêng tiêu đề thư thường đã đủ. Với những gì phức tạp hơn, parse MIME bằng thư viện chuẩn của ngôn ngữ bạn dùng. Thư viện đó sinh ra là để làm việc này.

Đọc lại:

curl https://anyhook.net/api/v1/events \
  -H "Authorization: Bearer ahk_live_…"

# the list carries no payloads; this returns one event with its body
curl https://anyhook.net/api/v1/events/<id> \
  -H "Authorization: Bearer ahk_live_…"

Cùng kiểu khởi tạo rồi nhận về tài khoản như một endpoint webhook. Hộp thư chỉ là một cửa trước khác.

Qua MCP

Nếu agent nói được MCP, nó không bao giờ phải đụng tới curl. Server có trong MCP registry chính thức với tên net.anyhook/anyhook, dưới dạng package npm anyhook-mcp và một endpoint streamable-HTTP từ xa tại https://anyhook.net/mcp:

anyhook_quickstart trả về trực tiếp một inbox_address (trong package npm, chạy không cần key; endpoint từ xa cần API key hoặc đăng nhập trước)
anyhook_inbox trả về địa chỉ của một App có sẵn, kèm URL webhook của App đó
anyhook_events / anyhook_inspect đọc những gì đã đến

Tool quickstart là toàn bộ quy trình onboarding. Một agent tìm thấy server trong registry có thể tự tạo cho mình một hộp thư và bắt đầu nhận mà không cần con người tham gia. Con người chỉ xuất hiện sau đó, nếu có, để nhận tài khoản về.

Cách hoạt động (và vì sao địa chỉ trông như vậy)

Bên dưới, chúng tôi cố ý không dựng một pipeline thứ hai:

Một rule catch-all của Cloudflare Email Routing chuyển mọi thư gửi tới domain cho chính Worker ở edge (lớp máy chủ biên của Cloudflare) đang nhận webhook
Worker tách phần local của địa chỉ tại dấu chấm cuối cùng: {user-slug}.{app-slug}@anyhook.net. Slug được làm sạch về [a-z0-9-] ngay lúc tạo, nên không bao giờ chứa dấu chấm, và nhờ cấu trúc đó, phép tách không bao giờ mơ hồ
Thư được đóng gói lại thành chính HTTP request mà lẽ ra nó sẽ là, và mọi thứ phía sau, gồm hạn mức, giới hạn payload, xếp hàng đợi, thử lại (retry), gửi tới các đích của bạn và nhật ký sự kiện, đều đi đúng code path mà webhook đi

Thư không khớp với một App có thật sẽ bị từ chối ngay ở bước SMTP, chứ không bị nuốt mất trong im lặng. Bên gửi không nhận được lỗi sẽ cho rằng thư đã tới nơi. Thư quá kích thước cũng bị trả về theo cách tương tự.

Hai đặc tính được kế thừa miễn phí từ phía webhook. Body của thư được mã hóa AES-256-GCM trước khi chạm tới database. Và hash của mỗi sự kiện được gộp vào một chuỗi băm theo từng App, được niêm phong hằng ngày, với root của mỗi ngày được commit lên một git repository công khai mà AnyHook không có thông tin xác thực nào. Nếu chúng tôi sửa một email đã lưu sau khi ngày của email đó đã được niêm phong, các điểm neo (anchor) đã công bố sẽ không còn xác minh được nữa.

Nó không phải là gì

Nó không gửi. Không trả lời, không thư gửi đi, không thông tin xác thực SMTP. Gửi thư là nơi các vấn đề về deliverability, căn chỉnh SPF/DKIM, uy tín IP và trách nhiệm về spam tồn tại. Đó là một lĩnh vực khác, với những kiểu lỗi khác. Nếu agent của bạn cần email hội thoại hai chiều đầy đủ như một sản phẩm, loại sản phẩm đó đã có (AgentMail gọi vốn dựa trên đúng luận điểm đó). Một hộp thư chỉ nhận gắn vào một dịch vụ trung chuyển webhook (webhook relay) là thứ hẹp hơn: một nhật ký sự kiện cho mọi thứ đi vào.

Nó không phải dịch vụ email dùng một lần. Mục đích sử dụng là thư do chính hệ thống của bạn sinh ra: xác nhận cho các tài khoản mà agent của bạn vận hành hợp lệ, thông báo từ các dịch vụ bạn tích hợp, biên nhận từ các luồng của chính bạn. Endpoint miễn phí bị giới hạn tốc độ (rate limit), có trần và có hạn dùng, và các kiểu lạm dụng sẽ bị chặn. Nếu điều khoản của một dịch vụ cấm đăng ký tự động, một hộp thư không thay đổi được điều đó.

Nó là polling, không phải push. Agent hỏi “có gì mới đến?” và không có gì đánh thức nó. Khi bạn cần độ trễ thấp hơn, gắn một destination_url và sự kiện sẽ được chuyển tiếp tới server của bạn ngay khi nó đến. Email trở thành webhook.

Dùng thử

# 1. mint an inbox (no signup)
curl -X POST https://anyhook.net/api/v1/quickstart

# 2. send any email to the inbox_address you got back

# 3. find it, then read it
curl https://anyhook.net/api/v1/events -H "Authorization: Bearer <api_key>"
curl https://anyhook.net/api/v1/events/<id> -H "Authorization: Bearer <api_key>"

Tổng thời gian thiết lập bằng đúng thời gian để email ở bước 2 đến nơi.