SDK（TypeScript / Python）

两个 SDK 都是盖在 REST API 上的薄客户端，没有额外运行时依赖。它们从你的代码读 key（从 SIMAIL_API_KEY 加载），替你设置头，并把 problem+json 错误变成带 agent 所需字段的异常。资源方法由 GET https://api.simail.ai/v0/openapi.json 的 OpenAPI 文档生成，所以始终和 API 参考一致；每个客户端也提供通用的 request()，可以打任意端点。

TypeScript

npm install @simail/sdk

可在 Node 22 及以后、Cloudflare Workers 和其他带标准 fetch 的运行时使用。没有运行时依赖。在服务器上用，不要放进浏览器：它需要你的 API key。

import { Simail, SimailApiError } from "@simail/sdk";

const simail = new Simail({ apiKey: process.env.SIMAIL_API_KEY });

// Call this first: during the private beta, sign-up is closed.
const beta = await simail.beta();

// Any endpoint through request(method, path, body?, { idempotencyKey? })
const inbox = await simail.request("POST", "/v0/inboxes", { username: "shop-helper", client_id: "shop-helper" }, { idempotencyKey: "create-shop-helper" });

try {
  await simail.request(
    "POST",
    "/v0/inboxes/shop-helper@simail.email/messages/msg_…/reply",
    { text: "Thanks! Your order shipped today." },
    { idempotencyKey: "reply-msg_…-1" },
  );
} catch (e) {
  if (e instanceof SimailApiError && !e.retryable) {
    // e.status, e.code ("thread_locked", "send_blocked", …), e.requestId, e.body (full problem+json)
  }
  throw e;
}

选项	默认
apiKey	无（没有 key 时只有 beta() 能用）
baseUrl	https://api.simail.ai
fetch	全局 fetch（代理或测试时传入你自己的）
userAgent	simail-sdk-ts/<version>

Python

pip install simail

Python 3.10 或更高，只用标准库。

import os
from simail import Simail, SimailApiError

simail = Simail(api_key=os.environ["SIMAIL_API_KEY"])
simail.beta()

try:
    simail.request(
        "POST",
        "/v0/inboxes/shop-helper@simail.email/messages/msg_…/reply",
        {"text": "Thanks! Your order shipped today."},
        idempotency_key="reply-msg_…-1",
    )
except SimailApiError as e:
    if not e.retryable:
        print(e.status, e.code, e.request_id)  # e.body has the full problem+json
    raise

Simail(api_key=None, base_url="https://api.simail.ai")；请求 30 秒后超时。

错误

两个 SDK 对任何非 2xx 响应都抛 SimailApiError：

字段	来自
status	HTTP 状态
code	problem+json 的 code（见错误码）
retryable	problem+json 的 retryable
requestId / request_id	request_id，也在 x-request-id 头里
body	整个 problem+json 对象，有的话包括 human_message、reasons 或 reason

SDK 不会自己重试，所以发送不会在你背后再发一次。只有 retryable 为真时才重试，等过 Retry-After，并用同一把幂等键。见幂等。

密钥

不要把 key 写死，也不要通过提示词传递。从环境变量或密钥管理器加载，并给每个 agent 自己的、作用域落在邮箱上的 key（认证）。