开发者平台

Temp Number API - 电话号码、短信和 OTP

开通虚拟电话号码、实时接收短信并自动完成 OTP 验证 - 通过简洁的 REST API,或直接在您的 AI 助手中完成。

REST · JSON 面向 AI 智能体的 MCP cURL · Node.js · Python · PHP
基础 URL https://api.temp-number.com/v1

简介

Temp Number API 围绕可预测的资源组织,使用标准 HTTP 动词,并且每个响应均返回 JSON。一个密钥即可读写仅限您本人的账户 - 不存在跨账户访问。

协议HTTPS · JSON
认证Bearer 密钥
版本v1(稳定版)
端点17 个可用

快速入门

从零开始到拿到验证码。只需选择一次语言 - 页面上的所有示例都会随之切换。

  1. 创建 API 密钥

    在控制台 → API 访问中创建密钥。密钥只显示一次:请将其保存为环境变量 TEMP_NUMBER_API_KEY。

  2. 查询余额

    每次调用都需在 Authorization 请求头中携带您的密钥。先从无副作用的请求开始:查询钱包余额。

    curl --request GET "https://api.temp-number.com/v1/account" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  3. 选择国家并查询库存

    GET /pricing 列出所有国家及每种时长的确切价格。然后确认目标国家的库存。

    curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  4. 购买号码

    每次购买都发送一个新的 Idempotency-Key。如果网络中断,请使用相同的密钥重试:您绝不会被重复扣费。请保存响应中的 data.id。

    curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Content-Type: application/json" \
      --header "Idempotency-Key: $(uuidgen)" \
      --data '{"country_code":"US","duration":"oneMonth"}'
  5. 读取短信

    每隔几秒轮询该号码,直到收到消息。您获得的是原始文本;请在您这边提取验证码。

    curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json"
  6. 没收到短信?取消并退款

    购买后 15 至 120 分钟内,未收到任何短信的号码可以取消,全额退款至您的钱包。

    curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
      --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
      --header "Accept: application/json" \
      --header "Idempotency-Key: $(uuidgen)"

身份验证

在每个请求的标准 Authorization 请求头中发送您的 API 密钥:

http
Authorization: Bearer YOUR_API_KEY
  • 请在 API 访问中创建密钥。密钥仅在创建时完整显示一次。
  • 每个集成使用一个密钥,这样撤销其中一个不会影响其他集成。修改密码会撤销所有密钥。
  • 缺失、格式错误或已吊销的密钥将返回 401。未验证邮箱或已被停用的账户将返回 403,code 为 email_unverified 或 account_suspended。
  • REST 密钥仅适用于 /v1。MCP 服务器使用其自己的登录方式或 MCP 密钥 - 请参阅 MCP 服务器。
请像对待密码一样保管您的密钥。请将其保存在服务器上,切勿放在网页或移动应用中。一旦密钥曾被记录到日志、提交到代码库或分享出去,请立即轮换。

基础 URL 与版本控制

所有端点均位于固定的 /v1 前缀下:

基础 URL
https://api.temp-number.com/v1

新增类变更(新字段、新端点或可选参数)发布时不会升级版本号,因此请忽略您不认识的字段。破坏性变更将在 /v2 下发布;您的集成绝不会被悄然迁移。机器可读的规范请参阅 OpenAPI 规范。

请求与响应

  • 发送 JSON 请求体时请使用 Content-Type: application/json,并在每个请求中携带 Accept: application/json。
  • 成功:{ "success": true, "data": …, "meta": {…} }。meta 包含数量统计、分页和金额汇总。
  • 错误:{ "success": false, "message": "…", "code": "…" }。请根据 code 进行分支处理;message 是给人看的。请参阅错误。
  • 时间采用 ISO 8601 格式。金额以 USD 计,保留两位小数,始终为您实际支付的价格。
  • 部分对象为兼容现有集成仍保留旧字段名(在参考文档中标记为已弃用)。新代码应忽略这些字段。
响应中绝不会出现上游服务商名称或批发成本。您看到的唯一价格就是从您钱包中扣除的金额 - 可放心展示给您自己的用户。

错误

错误使用标准 HTTP 状态码。业务错误带有稳定、机器可读的 code;部分错误还带有包含更多上下文的 details。

422 · 业务错误
{
  "success": false,
  "message": "Insufficient wallet balance.",
  "code": "insufficient_funds"
}
422 · 校验错误
{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}
状态code含义操作方法
400 - 购买、续费或取消请求中缺少 Idempotency-Key 请求头或其格式错误。响应体:{"error": "Missing Idempotency-Key header."} 在 Idempotency-Key 中发送一个 UUID。
401 - 缺少 Bearer 令牌、令牌格式错误,或密钥已被撤销。 检查 Authorization 请求头;如果密钥已被撤销,请创建新密钥。
403 email_unverified 该账户尚未验证邮箱地址。 请在网站上验证邮箱,然后重试。
403 account_suspended 该账户已被停用。 请联系客服。
403 kyc_required 该账户在购买新号码前必须完成身份验证。未扣任何费用;续费仍可正常使用。 请在账户设置中完成身份验证,然后重试。
403 - 该密钥没有 API 访问权限(例如 MCP 密钥),或通过 GET /receive-sms 查询了其他账户的号码。 使用 REST API 密钥;仅查询您自己的号码。
404 - 该号码、消息或国家不在您的账户中,或目前不在售。其他账户的 id 同样返回 404。 使用 GET /numbers 或 GET /pricing 重新获取列表。
404 private_email_closed 该私人收件箱已关闭,因为其号码已取消或退款。 没有可重试的内容。
409 - 该 Idempotency-Key 已用于不同的请求体,或使用它的首个请求仍在处理中。 新请求请使用新的密钥;对于处理中的请求,请等待后重试。
422 insufficient_funds 钱包余额不足以支付该价格。 为钱包充值后重试。
422 out_of_stock 在您查询价格和购买之间,该市场已售罄。 重新查询 GET /inventory,并选择其他时长或类型。
422 invalid_duration 该国家和号码类型不提供此时长。 重新获取 GET /pricing/{countryCode}。
422 - 验证失败(`errors` 对象会列出每个字段),或某条规则拒绝了该操作,例如在退款期之外取消。 阅读 `message`;修正请求,而不是直接重试。
429 - 已达到速率限制。 等待 Retry-After 请求头指定的时间,然后以退避方式重试。
503 purchases_paused 全平台暂停新购买。未扣任何费用;续费和取消仍可正常使用。 在 Retry-After 指定的时间(60 秒)后重试。
5xx - 我们这边出现了故障。 使用相同的 Idempotency-Key 重试 - 您绝不会被重复扣费。

速率限制

限制按密钥计算,涉及资金的调用还会额外按账户施加更严格的限制:

适用范围限制计入
所有端点60 / 分钟每个 API 密钥
购买、续费、取消10 / 分钟每个账户,在上述限制之外另计
GET /receive-sms60 / 分钟每个 API 密钥
GET /receive-sms30 / 分钟每个 API 密钥和电话号码
GET /receive-sms30 / 分钟每个 IP 地址

超出限制时会返回 429,并带有 Retry-After 请求头(单位:秒)。请至少等待该时长,然后使用带随机抖动的退避策略重试。响应中还包含 X-RateLimit-Limit 和 X-RateLimit-Remaining。

在等待短信?每个号码最多每 5 秒轮询一次。

幂等性

POST /numbers/buy、/renew 和 /cancel 必须携带 Idempotency-Key 请求头:即您为每个新操作生成的 UUID。如果网络中断,请使用相同的密钥重新发送相同的请求 - 您会收到原始响应(标记为 X-Idempotency-Replayed: true),且绝不会被重复扣费。

  • 缺少密钥:400。密钥最长 128 个字符,可包含字母、数字和 - _ . :
  • 同一密钥但请求体不同:409。同一密钥且首个请求仍在处理中:409 - 请稍候再试。
  • 密钥按账户和端点记录。切勿将同一个密钥用于另一次购买。

分页

GET /receive-sms 使用游标分页,按时间从新到旧排列。读取 meta.hasMore;当其为 true 时,将 meta.nextCursor 作为 cursor 回传,并保持相同的 phoneNumber。游标是不透明的 - 请勿自行构造或修改。

下一页
GET https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50&cursor=eyJkYXRlIjoiMjAyNi0wNS0xMyJ9

本身数据量较小的列表(/numbers、/pricing)会在一次响应中返回全部内容;私人收件箱使用 page 和 per_page。

可接受使用政策

该 API 专为开发者打造:适用于验证和 OTP 流程、自动化开户、QA 和系统测试,以及任何需要大规模接收短信或使用电话号码的产品。

  • 仅限用于正当的验证、开发和测试。
  • 禁止诈骗、垃圾信息、欺诈或欺骗行为。将号码用于诈骗或其他滥用行为的账户将被立即封禁且不另行通知,相关号码将被取消,且不予退款。
  • 不适用于受监管或与身份绑定的账户。我们的共享临时号码不支持银行、支付、加密货币、政府或其他需验证您法定身份(KYC/AML)的服务的短信验证 - 这类服务请使用您本人的手机号码。
我们会监控滥用行为。完整条款请参阅我们的服务条款。

API 参考

所有可用的 /v1 端点。右侧为您所选语言的请求示例;响应均为真实结构。

账户

读取您的钱包余额和结算货币。

GET /v1/account

获取账户余额

返回可用钱包余额及其货币。请在购买前查询,以便提前停止并给出明确的“请充值”提示。

响应字段
  • balancenumber

    可用钱包余额。

  • currencystring

    结算货币,USD。

错误
  • 401密钥缺失或无效。
curl --request GET "https://api.temp-number.com/v1/account" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "balance": 124.50,
  "currency": "USD"
}

定价与库存

浏览实时市场、每种时长的确切价格以及实时库存。

国家定价对象

单个国家及其可购买的所有套餐。price 是从您钱包扣除的最终金额;上游成本绝不会公开。

字段
  • country_codestring

    ISO 3166-1 alpha-2 代码,例如 US。

  • country_namestring

    显示名称。

  • packages[].number_typeenum

    voip 或 non_voip。

  • packages[].durationenum

    购买时发送的键:halfDay、oneDay、oneWeek、oneMonth、threeMonths、sixMonths 或 oneYear。每个国家提供的选项各不相同。

  • packages[].duration_labelstring

    可读标签,例如 "1 Month"。

  • packages[].pricenumber

    以 USD 计的最终价格。

  • packages[].original_pricenumber | null

    折扣前的价格(如适用)。

  • packages[].updated_atnull

    保留字段。

对象
{
  "country_code": "US",
  "country_name": "United States",
  "packages": [
    {
      "number_type": "voip",
      "duration": "oneMonth",
      "duration_label": "1 Month",
      "price": 4.99,
      "original_price": 5.99,
      "updated_at": null
    }
  ]
}
GET /v1/pricing

列出所有国家的定价

完整的实时目录:国家定价对象列表。price 字段是面向用户的最终 USD 价格,即您钱包实际扣除的金额。

返回

data 中的国家定价对象列表,附带 meta.count。

错误
  • 401密钥缺失或无效。
curl --request GET "https://api.temp-number.com/v1/pricing" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": [
    {
      "country_code": "US",
      "country_name": "United States",
      "packages": [
        {
          "number_type": "voip",
          "duration": "oneMonth",
          "duration_label": "1 Month",
          "price": 4.99,
          "original_price": 5.99,
          "updated_at": null
        },
        {
          "number_type": "voip",
          "duration": "threeMonths",
          "duration_label": "3 Months",
          "price": 12.99,
          "original_price": null,
          "updated_at": null
        }
      ]
    }
  ],
  "meta": { "count": 1 }
}
GET /v1/pricing/{countryCode}

获取单个国家的定价

单个国家的实时定价。404 表示该国家目前没有可用线路:请将其视为暂时“缺货”,而不是“从不销售”。

参数
  • countryCode string path 必填

    ISO 3166-1 alpha-2 国家代码,例如 US、GB、CA。

返回

data 中的单个国家定价对象。

错误
  • 404该国家目前没有可用线路。
curl --request GET "https://api.temp-number.com/v1/pricing/GB" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "country_code": "GB",
    "country_name": "United Kingdom",
    "packages": [
      {
        "number_type": "voip",
        "duration": "oneMonth",
        "duration_label": "1 Month",
        "price": 5.49,
        "original_price": null,
        "updated_at": null
      }
    ]
  }
}
GET /v1/inventory

查询库存

按国家和时长查询实时库存,让您能在任何人点击之前禁用“购买”按钮。省略 number_type 可在 types[] 中并列获取所有类型。绿色结果是很强的信号,但最终以实际购买为准。

参数
  • country_code string query 必填

    ISO 3166-1 alpha-2 国家代码。

  • duration enum query 可选

    来自 GET /pricing/{countryCode} 的时长键。省略则使用该线路的默认值。

    以下之一 halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum query 可选

    将查询限定为一种类型。省略则查看所有类型。

    以下之一 voipnon_voip
响应字段
  • stockinteger | null

    可用号码数量(省略 number_type 时为 types[] 的合计)。

  • availableboolean

    至少有一个号码可购买时为 true。

  • statusstring

    可读标签:In Stock、Out of Stock、Coming Soon…

  • types[]array

    仅在省略 number_type 时提供:该市场所售每种类型的 number_type、stock、available、status。

错误
  • 422所选条件下没有在售商品;details 中包含库存字段。
curl --request GET "https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "country_code": "US",
    "duration": "oneMonth",
    "number_type": null,
    "stock": 47,
    "available": true,
    "status": "In Stock",
    "types": [
      { "number_type": "voip", "stock": 0, "available": false, "status": "Out of Stock" },
      { "number_type": "non_voip", "stock": 47, "available": true, "status": "In Stock" }
    ]
  }
}

号码

列出、购买、续费和取消您的私人号码。涉及资金的调用具备幂等性,可安全重放。

号码对象

您账户中的一个号码。购买、续费和取消还会在 meta 中返回资金摘要:charged(或 refunded)、currency 和 wallet_balance_after。

字段
  • idinteger

    用于 /numbers/{id}/… 调用。Webhook 中以 number.rentalId 发送。

  • phone_numberstring

    E.164 格式,例如 +14035551234。

  • country_codestring | null

    ISO 3166-1 alpha-2。

  • country_namestring

    显示名称。

  • number_typeenum

    voip 或 non_voip。

  • statusenum

    active、expired、cancelled 或 refunded。

  • purchase_datestring

    ISO 8601,UTC。

  • expire_datestring

    ISO 8601,UTC。在此之后,号码将停止接收短信且无法续费。

为兼容旧版集成仍会发送的已弃用别名:country、provider、purchased_at 和 expires_at(毫秒级时间戳)。请勿基于它们进行开发。

对象
{
  "id": 1482,
  "phone_number": "+14035551234",
  "country_code": "US",
  "country_name": "United States",
  "number_type": "voip",
  "status": "active",
  "purchase_date": "2026-05-13T17:42:09Z",
  "expire_date": "2026-06-13T17:42:09Z"
}
GET /v1/numbers

列出您的号码

您账户中的所有号码,按时间从新到旧排列。使用 status=expiring_soon(10 天内到期的有效号码)来驱动续费提醒。

参数
  • status enum query 可选

    生命周期筛选。默认 all。

    以下之一 allactiveexpiring_soonexpiredcancelled
返回

data 中的号码对象列表;附带 meta.count 和 meta.status。

错误
  • 401密钥缺失或无效。
curl --request GET "https://api.temp-number.com/v1/numbers?status=expiring_soon" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": [
    {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    }
  ],
  "meta": { "count": 1, "status": "expiring_soon" }
}
POST /v1/numbers/buy 需要 Idempotency-Key

购买号码

在一个原子操作中分配新的私人号码并从您的钱包扣费。如果扣费后开通失败,扣款将被撤销:绝不会出现已付款却没有号码的情况。响应会显示扣费金额和扣费后的余额。

参数
  • country_code string body 必填

    来自 GET /pricing 的国家。

  • duration enum body 必填

    来自该国家 packages[] 的时长键 - 每个国家提供的选项各不相同。

    以下之一 halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear
  • number_type enum body 可选

    省略则使用该线路的默认值。

    以下之一 voipnon_voip
  • Idempotency-Key string header 必填

    一个 UUID,每次购买使用新的值,重试时复用。

返回

data 中的新号码对象;附带 meta.charged、meta.currency、meta.wallet_balance_after。

错误
  • 422insufficient_funds钱包余额不足以支付该价格。
  • 422out_of_stock自您查询库存后已售罄。
  • 422invalid_duration该国家/类型不提供此时长。
  • 403kyc_required需要先完成身份验证。未扣任何费用。
  • 503purchases_paused全平台暂停购买。Retry-After: 60。
curl --request POST "https://api.temp-number.com/v1/numbers/buy" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"country_code":"US","duration":"oneMonth","number_type":"voip"}'
响应
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "charged": 4.99,
    "currency": "USD",
    "wallet_balance_after": 119.51
  }
}
POST /v1/numbers/{id}/renew 需要 Idempotency-Key

续费号码

按所选套餐延长号码有效期。新的有效期会叠加在当前到期时间之上,因此提前续费不会有任何损失。价格为网站当前费率,由我们计算。已过期的号码无法续费:请购买新号码。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • package enum body 可选

    续费时长。默认 oneMonth。(duration 作为旧版别名仍可使用。)

    以下之一 oneMonththreeMonthssixMonthsoneYear
  • Idempotency-Key string header 必填

    一个 UUID,每次续费使用新的值,重试时复用。

返回

data 中更新后的号码对象;附带 meta.charged、meta.currency、meta.wallet_balance_after。

错误
  • 404不是您账户中的号码。
  • 422insufficient_funds钱包余额不足以支付续费。
  • 422已过期、已取消或不可续费。
curl --request POST "https://api.temp-number.com/v1/numbers/1482/renew" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"package":"threeMonths"}'
响应
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "active",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-09-13T17:42:09Z"
  },
  "meta": {
    "charged": 12.99,
    "currency": "USD",
    "wallet_balance_after": 106.52
  }
}
POST /v1/numbers/{id}/cancel 需要 Idempotency-Key

取消号码并退款

释放号码并将全额退款至您的钱包。仅允许在购买后 15 至 120 分钟内、号码处于有效状态且尚未收到任何短信时操作。不符合这些规则时,调用将以 422 被拒绝且不做任何更改;如果过早,details.seconds_until_open 会告诉您还需等待多久。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • Idempotency-Key string header 必填

    一个 UUID,重试时复用。

返回

data 中的号码对象(status 为 cancelled);附带 meta.refunded、meta.currency、meta.wallet_balance_after。

错误
  • 404不是您账户中的号码。
  • 422过早(不足 15 分钟)、过晚(超过 120 分钟)、已收到短信,或号码未处于有效状态。
curl --request POST "https://api.temp-number.com/v1/numbers/1482/cancel" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $(uuidgen)"
响应
{
  "success": true,
  "data": {
    "id": 1482,
    "phone_number": "+14035551234",
    "country_code": "US",
    "country_name": "United States",
    "number_type": "voip",
    "status": "cancelled",
    "purchase_date": "2026-05-13T17:42:09Z",
    "expire_date": "2026-06-13T17:42:09Z"
  },
  "meta": {
    "refunded": 4.99,
    "currency": "USD",
    "wallet_balance_after": 124.50
  }
}

SMS

读取您的号码收到的短信。您获得的是原始文本;验证码需由您自行提取。

短信消息对象

一条已收到的短信,与 GET /numbers/{id}/sms 返回的格式相同。(GET /receive-sms 使用 camelCase 变体,详见该端点。)

字段
  • idinteger

    短信 id。

  • fromstring

    发送方:电话号码或名称,例如 WhatsApp。

  • bodystring

    完整消息文本。

  • received_atstring

    ISO 8601,UTC。

仍会发送的已弃用别名:sender(= from)和 message(= body)。

对象
{
  "id": 9912,
  "from": "+18005550199",
  "body": "Your code is 432901",
  "received_at": "2026-05-13T17:43:14Z"
}
GET /v1/numbers/{id}/sms

获取号码及其短信

单个号码及其收到的所有短信,按时间从新到旧排列。最适合“查看此号码详情”视图,以及在等待验证码时轮询单个号码。不属于您的 id 将返回 404。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

返回

data.number(号码对象)和 data.messages(短信消息对象);meta.count。

错误
  • 404不是您账户中的号码。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "number": {
      "id": 1482,
      "phone_number": "+14035551234",
      "country_code": "US",
      "country_name": "United States",
      "number_type": "voip",
      "status": "active",
      "purchase_date": "2026-05-13T17:42:09Z",
      "expire_date": "2026-06-13T17:42:09Z"
    },
    "messages": [
      {
        "id": 9912,
        "from": "+18005550199",
        "body": "Your code is 432901",
        "received_at": "2026-05-13T17:43:14Z"
      }
    ]
  },
  "meta": { "count": 1 }
}
GET /v1/receive-sms

按电话号码接收短信

按电话号码(而非 id)获取您拥有号码的短信,使用游标分页。最适合消息量大的收件箱。不属于您的号码将返回 403。

参数
  • phoneNumber string query 必填

    E.164 格式或纯数字,例如 +14035551234。请对 + 进行 URL 编码。

  • limit integer query 可选

    每页数量 1-100。默认 50。

  • cursor string query 可选

    上一页的 meta.nextCursor。

响应字段
  • data.messages[].idinteger

    短信 id。

  • data.messages[].fromstring

    发送方。

  • data.messages[].tostring

    您的号码。

  • data.messages[].messagestring

    完整文本。

  • data.messages[].receivedAtstring

    ISO 8601。

  • meta.hasMore / nextCursorboolean / string | null

    将 nextCursor 作为 cursor 传入以获取下一页。

错误
  • 403该号码不在您的账户中。
  • 422phoneNumber 缺失或无效。
curl --request GET "https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "phoneNumber": "+14035551234",
    "purchaseStatus": "active",
    "messages": [
      {
        "id": 1842,
        "from": "WhatsApp",
        "to": "+14035551234",
        "message": "Your verification code is 483920.",
        "receivedAt": "2026-05-13T17:43:14+00:00"
      }
    ]
  },
  "meta": {
    "count": 1,
    "pageSize": 50,
    "hasMore": false,
    "nextCursor": null,
    "prevCursor": null,
    "requestedAt": "2026-05-13T17:43:20+00:00"
  }
}

私人邮箱

为每个私人号码提供一个免费、仅接收的 [email protected] 收件箱。每个号码一个地址。

私人邮箱对象

关联到单个号码的收件箱。

字段
  • addressstring | null

    地址;领取前为 null。

  • statusenum

    active 或 none。

  • unread_countinteger

    未读邮件。

  • created_atstring | null

    地址的领取时间。

  • eligibleboolean

    号码当前可以领取地址时为 true。

  • linked_numberstring

    所属的电话号码。

  • domainstring

    privnum.com

  • suggestionsstring[]

    符合条件时提供的名称建议。

对象
{
  "address": "[email protected]",
  "status": "active",
  "unread_count": 2,
  "created_at": "2026-07-03T10:15:00+00:00",
  "eligible": false,
  "linked_number": "+14035551234",
  "domain": "privnum.com",
  "suggestions": []
}
GET /v1/numbers/{id}/private-email

获取私人邮箱

号码的地址;若尚未领取,则返回是否可以领取以及一些名称建议。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

返回

data 中的私人邮箱对象。

错误
  • 404不是您账户中的号码。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "address": null,
    "status": "none",
    "unread_count": 0,
    "created_at": null,
    "eligible": true,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": ["alex.smith", "alex.smith42"]
  }
}
GET /v1/numbers/{id}/private-email/availability

检查名称

在领取前实时检查名称是否有效且可用。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • local_part string query 必填

    @ 之前的部分:3-64 个字母、数字、点、短横线或下划线。

响应字段
  • availableboolean

    您可以领取时为 true。

  • reasonenum | null

    too_short、too_long、invalid、reserved 或 taken。

错误
  • 404不是您账户中的号码。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "local_part": "alex.smith",
    "address": "[email protected]",
    "available": true,
    "reason": null,
    "message": "Available"
  }
}
POST /v1/numbers/{id}/private-email

领取地址

为有效号码分配地址。免费,每个号码一个,已领取的地址绝不会分配给其他人。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • local_part string body 必填

    您检查的名称。

返回

data 中的私人邮箱对象。

错误
  • 404不是您的号码,或尚未领取地址。
  • 422名称已被占用或无效(details.reason),该号码已有地址,或该号码未处于有效状态。
curl --request POST "https://api.temp-number.com/v1/numbers/1482/private-email" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"local_part":"alex.smith"}'
响应
{
  "success": true,
  "data": {
    "address": "[email protected]",
    "status": "active",
    "unread_count": 0,
    "created_at": "2026-07-03T10:15:00+00:00",
    "eligible": false,
    "linked_number": "+14035551234",
    "domain": "privnum.com",
    "suggestions": []
  }
}
GET /v1/numbers/{id}/private-email/inbox

列出邮件

邮件摘要,按时间从新到旧排列,采用基于页码的分页,未读数量位于顶层。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • page integer query 可选

    页码。默认 1。

  • per_page integer query 可选

    1-100。默认 25。

响应字段
  • data[]array

    id、from_email、from_name、subject、preview、attachment_count、is_read、received_at。

  • metaobject

    current_page、per_page、total、last_page。

  • unread_countinteger

    位于顶层,与 data 并列。

错误
  • 404不是您的号码,或尚未领取地址。
  • 404private_email_closed该号码已取消或已退款。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": [
    {
      "id": 77,
      "from_email": "[email protected]",
      "from_name": "Example Billing",
      "subject": "Your receipt",
      "preview": "Thanks for your order…",
      "attachment_count": 1,
      "is_read": false,
      "received_at": "2026-07-04T08:01:12+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 },
  "unread_count": 1
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/body

读取邮件

完整邮件(HTML 和纯文本)及其附件列表。读取后将标记为已读。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • messageId integer path 必填

    收件箱列表中的邮件 id。

错误
  • 404不是您的号码,或尚未领取地址。
  • 404private_email_closed该号码已取消或已退款。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": {
    "id": 77,
    "subject": "Your receipt",
    "from_email": "[email protected]",
    "from_name": "Example Billing",
    "received_at": "2026-07-04T08:01:12+00:00",
    "html": "<p>Thanks for your order…</p>",
    "text": "Thanks for your order…",
    "attachments": [
      { "index": 0, "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 48211 }
    ]
  }
}
GET /v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}

下载附件

原始文件,带有其自身的 Content-Type 和文件名。index 来自邮件的 attachments[]。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • messageId integer path 必填

    收件箱列表中的邮件 id。

  • index integer path 必填

    来自“读取邮件”的 attachments[].index。

错误
  • 404不是您的号码,或尚未领取地址。
  • 404private_email_closed该号码已取消或已退款。
  • 404该索引处没有附件。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --output receipt.pdf
响应
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf

<binary file>
DELETE /v1/numbers/{id}/private-email/inbox/{messageId}

删除邮件

删除该邮件及其附件。

参数
  • id integer path 必填

    来自 GET /numbers 的号码 id。

  • messageId integer path 必填

    收件箱列表中的邮件 id。

错误
  • 404不是您的号码,或尚未领取地址。
  • 404private_email_closed该号码已取消或已退款。
curl --request DELETE "https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77" \
  --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \
  --header "Accept: application/json"
响应
{
  "success": true,
  "data": null
}

AI 与 MCP

让 AI 助手直接使用您的账户,或为编程智能体提供基于 API 开发所需的一切。

MCP 服务器

除 REST API 外,我们还提供 Model Context Protocol 服务器。将其连接到 Claude、ChatGPT 或您的编辑器后,助手即可通过原生工具查询价格和库存、购买号码并读取短信,您无需编写任何代码。初次接触 MCP?请先阅读 MCP 服务器概览。

端点
MCP 端点 · 可流式 HTTP
https://mcp.temp-number.com/mcp

登录流程说明

  • 将该 URL 添加到您的 AI 应用中。应用会跳转到 Temp Number,让您使用自己的账户登录(OAuth 2.1 + PKCE),无需复制密钥。
  • 在授权页面上,您可以选择助手的权限。读取余额、价格、您的号码及其短信始终包含在内。允许购买(使用钱包购买、续费和取消)默认关闭,需您勾选才会开启。
  • 所有连接都列在 控制台 → MCP Server → Connected apps 中,您可以随时断开连接。
  • 更想用密钥(CI、脚本、无界面智能体)?在同一页面创建 MCP 密钥,并通过 Authorization: Bearer <key> 发送。MCP 密钥与 REST API 密钥不可互换。

工具

工具功能说明需要“允许购买”
get-balance获取已认证账户的钱包余额和结算货币。否
get-pricing返回所有国家或单个 ISO 国家代码的当前价格目录。否
get-inventory查看某个国家、时长及可选号码类型的实时库存情况。否
purchase-number使用钱包资金为已认证账户购买一个私人号码。是
list-active-numbers返回已认证账户拥有的号码,可按状态筛选。否
check-sms获取已认证账户所拥有的已购号码 ID 的短信。否
renew-number按 ID 续费已购买的号码,可选择时长套餐。是
cancel-number按 ID 取消已购买的号码,并退还符合条件的钱包款项。是

连接您的 AI 工具

选择您的应用。大多数应用一键即可连接:登录 Temp Number,勾选助手可执行的操作,然后点击 Allow。

Claude - claude.ai、桌面版和移动版

无需安装。支持浏览器、桌面应用和移动端。

  1. 点击 Add to Claude。Claude 打开后已自动填好 Temp Number 及其 URL。点击 Add。
  2. 点击 Connect,登录 Temp Number,选择是否允许 Claude 进行购买,然后点击 Allow。
  3. 在任意对话中打开 + 菜单 → Connectors,并开启 Temp Number。试试:“一个美国号码一个月多少钱?”
Team 和 Enterprise:由所有者在“组织设置 → 连接器”中添加一次连接器。之后每位成员使用自己的 Temp Number 账户登录,各自从自己的钱包中扣费。

没有按钮?在 Claude 中前往 Customize → Connectors → Add custom connector 并粘贴 MCP 端点。支持 Claude 请求头选项的组织也可以通过 Authorization: Bearer <key> 发送 MCP 密钥,而无需登录。

llms.txt 与智能体提示词

正在使用 AI 编程助手开发?把下面的上下文交给它,它就能一次性正确集成 API,包括身份验证、幂等性和速率限制。

llms.txt OpenAPI 规范
prompt.md
You are integrating the Temp Number REST API. Read the full, machine-readable reference before writing any code:

- API reference (llms.txt): https://temp-number.com/developers/llms.txt
- OpenAPI spec: https://api.temp-number.com/api.json
- Base URL: https://api.temp-number.com/v1
- MCP server (for AI agents that call tools directly): https://mcp.temp-number.com/mcp - sign in with OAuth, or send an MCP key as a Bearer token.

Rules: authenticate every request with `Authorization: Bearer <YOUR_API_KEY>` (created in the dashboard → API Access) and keep the key in an environment variable, never in code; send and accept JSON over HTTPS; send a unique `Idempotency-Key` (UUID) header on every POST that buys, renews or cancels - it is required, and retries must reuse the same key; branch on the `code` field of error responses, not on the message text; on HTTP 429 or 503, wait for the `Retry-After` header. All prices are final USD.

Task: <describe what you want to build - e.g. "buy a US number, wait for the verification SMS, then cancel it if it never arrives">.
https://temp-number.com/developers/llms.txt 是所有端点的实时纯文本摘要;OpenAPI 规范则是带类型的接口契约。两者都会随 API 同步更新。

资源

更新内容及获取帮助的途径。

更新日志

仅有新增类变更 - /v1 上的内容均未被移除。

  • NewMCP:使用您的 Temp Number 账户登录

    一键“添加到 Claude”,还支持 ChatGPT、Claude Code、Codex、Cursor 和 VS Code,无需复制密钥。您可以在授权页面上选择是否允许 AI 消费。

  • Docs文档有了新家

    快速入门、搜索,以及 cURL、Node.js、Python 和 PHP 的所有示例。错误、速率限制和退款现已与实际 API 完全一致。

  • New全站 llms.txt

    为 AI 助手提供的纯文本服务概览,并链接到适合智能体使用的 API 参考文档。

  • New连接您的 AI 工具

    Claude Code、Codex、Cursor 和 VS Code 的配置方法,并为 Cursor 和 VS Code 提供一键安装链接。

  • NewOpenAPI 规范

    机器可读的接口规范位于 https://api.temp-number.com/api.json。

  • Improved对象与参考文档一致

    号码和短信使用 ISO 8601 日期以及 from/body 字段。错误会附带机器可读的代码(out_of_stock、insufficient_funds、invalid_duration)。省略 number_type 时,/inventory 会报告所有号码类型。旧字段名仍可作为已弃用的别名使用。

  • New私人邮箱端点

    为号码领取免费的 [email protected] 收件箱,通过 API 读取邮件并下载附件。

  • NewMCP 服务器

    AI 智能体可使用 MCP 密钥,将查询价格、购买号码和读取短信作为工具调用。

  • Launch公开 REST API v1

    账户、定价、库存、号码生命周期和短信,使用 Bearer 令牌认证。

支持

遇到问题,或发现文档与 API 实际行为不一致?联系我们 - 请提供端点、请求时间和响应体(切勿提供您的 API 密钥)。

准备好开始构建了吗?

创建密钥,不到一分钟即可完成首次调用。

登录以开始