首页 / 开发者
简介
Temp Number API 围绕可预测的资源组织,使用标准 HTTP 动词,并且每个响应均返回 JSON。一个密钥即可读写仅限您本人的账户 - 不存在跨账户访问。
快速入门
从零开始到拿到验证码。只需选择一次语言 - 页面上的所有示例都会随之切换。
-
创建 API 密钥
在控制台 → API 访问中创建密钥。密钥只显示一次:请将其保存为环境变量
TEMP_NUMBER_API_KEY。 -
查询余额
每次调用都需在 Authorization 请求头中携带您的密钥。先从无副作用的请求开始:查询钱包余额。
curl --request GET "https://api.temp-number.com/v1/account" \ --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \ --header "Accept: application/json"const response = await fetch("https://api.temp-number.com/v1/account", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/account", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/account'); $result = $response->json(); -
选择国家并查询库存
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"const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/inventory", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, params={"country_code": "US", "duration": "oneMonth"}, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/inventory', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
购买号码
每次购买都发送一个新的 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"}'import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/buy", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ country_code: "US", duration: "oneMonth" }), }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/buy", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, json={"country_code": "US", "duration": "oneMonth"}, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/buy', [ 'country_code' => 'US', 'duration' => 'oneMonth', ]); $result = $response->json(); -
读取短信
每隔几秒轮询该号码,直到收到消息。您获得的是原始文本;请在您这边提取验证码。
curl --request GET "https://api.temp-number.com/v1/numbers/1482/sms" \ --header "Authorization: Bearer $TEMP_NUMBER_API_KEY" \ --header "Accept: application/json"const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", { headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", }, }); const result = await response.json(); console.log(response.status, result);import os import requests response = requests.get( "https://api.temp-number.com/v1/numbers/1482/sms", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", }, timeout=30, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->get('https://api.temp-number.com/v1/numbers/1482/sms'); $result = $response->json(); -
没收到短信?取消并退款
购买后 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)"import { randomUUID } from "node:crypto"; const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`, Accept: "application/json", "Idempotency-Key": randomUUID(), }, }); const result = await response.json(); console.log(response.status, result);import os import uuid import requests response = requests.post( "https://api.temp-number.com/v1/numbers/1482/cancel", headers={ "Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}", "Accept": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, timeout=60, ) print(response.status_code, response.json())use Illuminate\Support\Facades\Http; use Illuminate\Support\Str; // config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')] $response = Http::withToken(config('services.temp_number.key')) ->acceptJson() ->withHeaders(['Idempotency-Key' => (string) Str::uuid()]) ->timeout(60) ->post('https://api.temp-number.com/v1/numbers/1482/cancel'); $result = $response->json();
身份验证
在每个请求的标准 Authorization 请求头中发送您的 API 密钥:
Authorization: Bearer YOUR_API_KEY
- 请在 API 访问中创建密钥。密钥仅在创建时完整显示一次。
- 每个集成使用一个密钥,这样撤销其中一个不会影响其他集成。修改密码会撤销所有密钥。
- 缺失、格式错误或已吊销的密钥将返回
401。未验证邮箱或已被停用的账户将返回403,code为email_unverified或account_suspended。 - REST 密钥仅适用于
/v1。MCP 服务器使用其自己的登录方式或 MCP 密钥 - 请参阅 MCP 服务器。
基础 URL 与版本控制
所有端点均位于固定的 /v1 前缀下:
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。
{
"success": false,
"message": "Insufficient wallet balance.",
"code": "insufficient_funds"
}
{
"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-sms | 60 / 分钟 | 每个 API 密钥 |
| GET /receive-sms | 30 / 分钟 | 每个 API 密钥和电话号码 |
| GET /receive-sms | 30 / 分钟 | 每个 IP 地址 |
超出限制时会返回 429,并带有 Retry-After 请求头(单位:秒)。请至少等待该时长,然后使用带随机抖动的退避策略重试。响应中还包含 X-RateLimit-Limit 和 X-RateLimit-Remaining。
幂等性
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 参考
所有可用的 /v1 端点。右侧为您所选语言的请求示例;响应均为真实结构。
账户
读取您的钱包余额和结算货币。
/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"
const response = await fetch("https://api.temp-number.com/v1/account", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/account",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/account');
$result = $response->json();
{
"success": true,
"balance": 124.50,
"currency": "USD"
}
定价与库存
浏览实时市场、每种时长的确切价格以及实时库存。
国家定价对象
单个国家及其可购买的所有套餐。price 是从您钱包扣除的最终金额;上游成本绝不会公开。
字段-
country_codestringISO 3166-1 alpha-2 代码,例如 US。
-
country_namestring显示名称。
-
packages[].number_typeenumvoip 或 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
}
]
}
/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"
const response = await fetch("https://api.temp-number.com/v1/pricing", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing');
$result = $response->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 }
}
/v1/pricing/{countryCode}
获取单个国家的定价
单个国家的实时定价。404 表示该国家目前没有可用线路:请将其视为暂时“缺货”,而不是“从不销售”。
参数-
countryCodestring 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"
const response = await fetch("https://api.temp-number.com/v1/pricing/GB", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/pricing/GB",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/pricing/GB');
$result = $response->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
}
]
}
}
/v1/inventory
查询库存
按国家和时长查询实时库存,让您能在任何人点击之前禁用“购买”按钮。省略 number_type 可在 types[] 中并列获取所有类型。绿色结果是很强的信号,但最终以实际购买为准。
参数-
country_codestring query 必填ISO 3166-1 alpha-2 国家代码。
-
durationenum query 可选来自 GET /pricing/{countryCode} 的时长键。省略则使用该线路的默认值。
以下之一halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum 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"
const response = await fetch("https://api.temp-number.com/v1/inventory?country_code=US&duration=oneMonth", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/inventory",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"country_code": "US", "duration": "oneMonth"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/inventory', [
'country_code' => 'US',
'duration' => 'oneMonth',
]);
$result = $response->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_numberstringE.164 格式,例如 +14035551234。
-
country_codestring | nullISO 3166-1 alpha-2。
-
country_namestring显示名称。
-
number_typeenumvoip 或 non_voip。
-
statusenumactive、expired、cancelled 或 refunded。
-
purchase_datestringISO 8601,UTC。
-
expire_datestringISO 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"
}
/v1/numbers
列出您的号码
您账户中的所有号码,按时间从新到旧排列。使用 status=expiring_soon(10 天内到期的有效号码)来驱动续费提醒。
参数-
statusenum 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"
const response = await fetch("https://api.temp-number.com/v1/numbers?status=expiring_soon", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"status": "expiring_soon"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers', [
'status' => 'expiring_soon',
]);
$result = $response->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" }
}
/v1/numbers/buy
需要 Idempotency-Key 购买号码
在一个原子操作中分配新的私人号码并从您的钱包扣费。如果扣费后开通失败,扣款将被撤销:绝不会出现已付款却没有号码的情况。响应会显示扣费金额和扣费后的余额。
参数-
country_codestring body 必填来自 GET /pricing 的国家。
-
durationenum body 必填来自该国家 packages[] 的时长键 - 每个国家提供的选项各不相同。
以下之一halfDayoneDayoneWeekoneMonththreeMonthssixMonthsoneYear -
number_typeenum body 可选省略则使用该线路的默认值。
以下之一voipnon_voip -
Idempotency-Keystring header 必填一个 UUID,每次购买使用新的值,重试时复用。
data 中的新号码对象;附带 meta.charged、meta.currency、meta.wallet_balance_after。
错误- 422
insufficient_funds钱包余额不足以支付该价格。 - 422
out_of_stock自您查询库存后已售罄。 - 422
invalid_duration该国家/类型不提供此时长。 - 403
kyc_required需要先完成身份验证。未扣任何费用。 - 503
purchases_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/buy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ country_code: "US", duration: "oneMonth", number_type: "voip" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/buy",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"country_code": "US", "duration": "oneMonth", "number_type": "voip"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/buy', [
'country_code' => 'US',
'duration' => 'oneMonth',
'number_type' => 'voip',
]);
$result = $response->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": {
"charged": 4.99,
"currency": "USD",
"wallet_balance_after": 119.51
}
}
/v1/numbers/{id}/renew
需要 Idempotency-Key 续费号码
按所选套餐延长号码有效期。新的有效期会叠加在当前到期时间之上,因此提前续费不会有任何损失。价格为网站当前费率,由我们计算。已过期的号码无法续费:请购买新号码。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
packageenum body 可选续费时长。默认 oneMonth。(duration 作为旧版别名仍可使用。)
以下之一oneMonththreeMonthssixMonthsoneYear -
Idempotency-Keystring header 必填一个 UUID,每次续费使用新的值,重试时复用。
data 中更新后的号码对象;附带 meta.charged、meta.currency、meta.wallet_balance_after。
错误- 404不是您账户中的号码。
- 422
insufficient_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"}'
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/renew", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({ package: "threeMonths" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/renew",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"package": "threeMonths"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/renew', [
'package' => 'threeMonths',
]);
$result = $response->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-09-13T17:42:09Z"
},
"meta": {
"charged": 12.99,
"currency": "USD",
"wallet_balance_after": 106.52
}
}
/v1/numbers/{id}/cancel
需要 Idempotency-Key 取消号码并退款
释放号码并将全额退款至您的钱包。仅允许在购买后 15 至 120 分钟内、号码处于有效状态且尚未收到任何短信时操作。不符合这些规则时,调用将以 422 被拒绝且不做任何更改;如果过早,details.seconds_until_open 会告诉您还需等待多久。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
Idempotency-Keystring 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)"
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/cancel", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Idempotency-Key": randomUUID(),
},
});
const result = await response.json();
console.log(response.status, result);
import os
import uuid
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/cancel",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/cancel');
$result = $response->json();
{
"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_atstringISO 8601,UTC。
仍会发送的已弃用别名:sender(= from)和 message(= body)。
{
"id": 9912,
"from": "+18005550199",
"body": "Your code is 432901",
"received_at": "2026-05-13T17:43:14Z"
}
/v1/numbers/{id}/sms
获取号码及其短信
单个号码及其收到的所有短信,按时间从新到旧排列。最适合“查看此号码详情”视图,以及在等待验证码时轮询单个号码。不属于您的 id 将返回 404。
参数-
idinteger 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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/sms", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/sms');
$result = $response->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 }
}
/v1/receive-sms
按电话号码接收短信
按电话号码(而非 id)获取您拥有号码的短信,使用游标分页。最适合消息量大的收件箱。不属于您的号码将返回 403。
参数-
phoneNumberstring query 必填E.164 格式或纯数字,例如 +14035551234。请对 + 进行 URL 编码。
-
limitinteger query 可选每页数量 1-100。默认 50。
-
cursorstring query 可选上一页的 meta.nextCursor。
-
data.messages[].idinteger短信 id。
-
data.messages[].fromstring发送方。
-
data.messages[].tostring您的号码。
-
data.messages[].messagestring完整文本。
-
data.messages[].receivedAtstringISO 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"
const response = await fetch("https://api.temp-number.com/v1/receive-sms?phoneNumber=%2B14035551234&limit=50", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/receive-sms",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"phoneNumber": "+14035551234", "limit": 50},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/receive-sms', [
'phoneNumber' => '+14035551234',
'limit' => 50,
]);
$result = $response->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。
-
statusenumactive 或 none。
-
unread_countinteger未读邮件。
-
created_atstring | null地址的领取时间。
-
eligibleboolean号码当前可以领取地址时为 true。
-
linked_numberstring所属的电话号码。
-
domainstringprivnum.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": []
}
/v1/numbers/{id}/private-email
获取私人邮箱
号码的地址;若尚未领取,则返回是否可以领取以及一些名称建议。
参数-
idinteger 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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email');
$result = $response->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"]
}
}
/v1/numbers/{id}/private-email/availability
检查名称
在领取前实时检查名称是否有效且可用。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
local_partstring query 必填@ 之前的部分:3-64 个字母、数字、点、短横线或下划线。
-
availableboolean您可以领取时为 true。
-
reasonenum | nulltoo_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/availability?local_part=alex.smith", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/availability",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"local_part": "alex.smith"},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/availability', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"success": true,
"data": {
"local_part": "alex.smith",
"address": "[email protected]",
"available": true,
"reason": null,
"message": "Available"
}
}
/v1/numbers/{id}/private-email
领取地址
为有效号码分配地址。免费,每个号码一个,已领取的地址绝不会分配给其他人。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
local_partstring 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"}'
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({ local_part: "alex.smith" }),
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.post(
"https://api.temp-number.com/v1/numbers/1482/private-email",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
json={"local_part": "alex.smith"},
timeout=60,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->timeout(60)
->post('https://api.temp-number.com/v1/numbers/1482/private-email', [
'local_part' => 'alex.smith',
]);
$result = $response->json();
{
"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": []
}
}
/v1/numbers/{id}/private-email/inbox
列出邮件
邮件摘要,按时间从新到旧排列,采用基于页码的分页,未读数量位于顶层。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
pageinteger query 可选页码。默认 1。
-
per_pageinteger query 可选1-100。默认 25。
-
data[]arrayid、from_email、from_name、subject、preview、attachment_count、is_read、received_at。
-
metaobjectcurrent_page、per_page、total、last_page。
-
unread_countinteger位于顶层,与 data 并列。
- 404不是您的号码,或尚未领取地址。
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox?page=1&per_page=25", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
params={"page": 1, "per_page": 25},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox', [
'page' => 1,
'per_page' => 25,
]);
$result = $response->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
}
/v1/numbers/{id}/private-email/inbox/{messageId}/body
读取邮件
完整邮件(HTML 和纯文本)及其附件列表。读取后将标记为已读。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
messageIdinteger path 必填收件箱列表中的邮件 id。
- 404不是您的号码,或尚未领取地址。
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/body');
$result = $response->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 }
]
}
}
/v1/numbers/{id}/private-email/inbox/{messageId}/attachments/{index}
下载附件
原始文件,带有其自身的 Content-Type 和文件名。index 来自邮件的 attachments[]。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
messageIdinteger path 必填收件箱列表中的邮件 id。
-
indexinteger path 必填来自“读取邮件”的 attachments[].index。
- 404不是您的号码,或尚未领取地址。
- 404
private_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
import { writeFile } from "node:fs/promises";
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0", {
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
},
});
await writeFile("receipt.pdf", Buffer.from(await response.arrayBuffer()));
import os
import requests
response = requests.get(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
},
timeout=30,
)
with open("receipt.pdf", "wb") as file:
file.write(response.content)
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->sink(storage_path('receipt.pdf'))
->get('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77/attachments/0');
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename=receipt.pdf
<binary file>
/v1/numbers/{id}/private-email/inbox/{messageId}
删除邮件
删除该邮件及其附件。
参数-
idinteger path 必填来自 GET /numbers 的号码 id。
-
messageIdinteger path 必填收件箱列表中的邮件 id。
- 404不是您的号码,或尚未领取地址。
- 404
private_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"
const response = await fetch("https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.TEMP_NUMBER_API_KEY}`,
Accept: "application/json",
},
});
const result = await response.json();
console.log(response.status, result);
import os
import requests
response = requests.delete(
"https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77",
headers={
"Authorization": f"Bearer {os.environ['TEMP_NUMBER_API_KEY']}",
"Accept": "application/json",
},
timeout=30,
)
print(response.status_code, response.json())
use Illuminate\Support\Facades\Http;
// config/services.php: 'temp_number' => ['key' => env('TEMP_NUMBER_API_KEY')]
$response = Http::withToken(config('services.temp_number.key'))
->acceptJson()
->delete('https://api.temp-number.com/v1/numbers/1482/private-email/inbox/77');
$result = $response->json();
{
"success": true,
"data": null
}
AI 与 MCP
让 AI 助手直接使用您的账户,或为编程智能体提供基于 API 开发所需的一切。
MCP 服务器
除 REST API 外,我们还提供 Model Context Protocol 服务器。将其连接到 Claude、ChatGPT 或您的编辑器后,助手即可通过原生工具查询价格和库存、购买号码并读取短信,您无需编写任何代码。初次接触 MCP?请先阅读 MCP 服务器概览。
端点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、桌面版和移动版
无需安装。支持浏览器、桌面应用和移动端。
- 点击 Add to Claude。Claude 打开后已自动填好 Temp Number 及其 URL。点击 Add。
- 点击 Connect,登录 Temp Number,选择是否允许 Claude 进行购买,然后点击 Allow。
- 在任意对话中打开 + 菜单 → Connectors,并开启 Temp Number。试试:“一个美国号码一个月多少钱?”
没有按钮?在 Claude 中前往 Customize → Connectors → Add custom connector 并粘贴 MCP 端点。支持 Claude 请求头选项的组织也可以通过 Authorization: Bearer <key> 发送 MCP 密钥,而无需登录。
ChatGPT
需要网页版 ChatGPT Business、Enterprise 或 Edu。Business 版需由管理员或所有者添加。
- 复制下方的服务器 URL,然后点击打开 ChatGPT,进入其 Plugins 页面。ChatGPT 没有可自动填写的链接。
- 点击 + → Add custom MCP server。将其命名为 Temp Number,并在 Connection 下粘贴 URL。
- 将身份验证设为 OAuth,接受风险提示,然后点击 Create as a plugin。
- 当 ChatGPT 提示时,登录 Temp Number,选择是否允许 ChatGPT 进行购买,然后点击 Allow。
- 在新对话中输入 @ 并选择 Temp Number。试试:“一个美国号码一个月多少钱?”
https://mcp.temp-number.com/mcp
Claude Code
添加一次服务器,然后在 Claude Code 中登录。
claude mcp add --transport http temp-number https://mcp.temp-number.com/mcp
- 启动 Claude Code 并输入
/mcp。 - 选择 temp-number → Authenticate。浏览器会打开页面:登录后点击 Allow。
改用 MCP 密钥(CI / 无界面)
export TEMPNUMBER_MCP_KEY=your-mcp-key
claude mcp add --transport http temp-number \
https://mcp.temp-number.com/mcp \
--header "Authorization: Bearer $TEMPNUMBER_MCP_KEY"
Codex CLI
添加服务器后登录。Codex 会为您保存会话。
codex mcp add temp-number --url https://mcp.temp-number.com/mcp
codex mcp login temp-number
改用 MCP 密钥(CI / 无界面)
位于 ~/.codex/config.toml。密钥从环境变量读取,因此可以放心分享该文件。
[mcp_servers.temp-number]
url = "https://mcp.temp-number.com/mcp"
bearer_token_env_var = "TEMPNUMBER_MCP_KEY"
Cursor
一键连接,然后在 Cursor 提示时登录。
或将其添加到 .cursor/mcp.json(或 ~/.cursor/mcp.json)。之后 Cursor 会在服务器旁显示 Needs login:点击它,登录后点击 Allow。
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp"
}
}
}
改用 MCP 密钥
{
"mcpServers": {
"temp-number": {
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TEMPNUMBER_MCP_KEY}"
}
}
}
}
VS Code (GitHub Copilot)
一键连接,首次运行工具时登录。
或将其添加到 .vscode/mcp.json,注意键名是 servers,而不是 mcpServers。
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp"
}
}
}
改用 MCP 密钥
VS Code 只会询问一次密钥,并将其保存在安全存储中。
{
"servers": {
"temp-number": {
"type": "http",
"url": "https://mcp.temp-number.com/mcp",
"headers": {
"Authorization": "Bearer ${input:tempnumber-mcp-key}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "tempnumber-mcp-key",
"description": "Temp Number MCP key",
"password": true
}
]
}
其他 MCP 应用
Windsurf、Zed、LibreChat、您自己的智能体…
- 将 MCP 端点添加为远程(可流式 HTTP)服务器。支持登录的应用会自动在
https://mcp.temp-number.com/.well-known/oauth-protected-resource找到它,并打开 Temp Number 授权页面。 - 不支持登录的应用可以通过
Authorization: Bearer <key>发送 MCP 密钥。
https://mcp.temp-number.com/mcp
llms.txt 与智能体提示词
正在使用 AI 编程助手开发?把下面的上下文交给它,它就能一次性正确集成 API,包括身份验证、幂等性和速率限制。
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 令牌认证。
准备好开始构建了吗?
创建密钥,不到一分钟即可完成首次调用。