开发者 → REST API

REST API 参考文档

通过 HTTPS 管理域名、DNS、SSL 和应用服务器。JSON 输入，JSON 输出，统一的基础 URL。

基础 URL

https://nameocean.net/api/v1

身份验证

Authorization: Bearer <key>，密钥可在控制台 → API 密钥中获取。

OpenAPI 3.1

/api/v1/openapi.json · 可导入 Postman、Insomnia 或 Bruno，也可用于生成客户端。

权限范围

每个密钥都带有相应权限。GET 请求需要 <area>:read，其他方法需要 <area>:write；下方每个端点都列出了所需权限。缺少权限时将返回 403，代码为 missing_scope，并附带 required_scopes。查看所有权限范围。

错误

所有错误的结构均相同：一条面向用户和 AI 代理的可读消息，以及一个可用于分支判断的稳定代码。如有出错的输入项，field 会指明其名称。

HTTP 400

{"error": "ip: Enter a valid IPv4 or IPv6 address.", "code": "invalid_field", "field": "ip"}

代码: invalid_request invalid_field unauthorized forbidden missing_scope not_found conflict already_exists insufficient_credit domain_unavailable premium_not_accepted email_not_confirmed contact_details_missing renewed_recently nameservers_not_nameocean rate_limited idempotency_key_reused idempotency_in_progress upstream_error unavailable limit_reached not_eligible mx_records_exist forwarding_off invalid_code refused not_approved

速率限制

每个账户每分钟最多 120 个请求。每个响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset（距离空出可用额度的秒数）。超出限制时返回 429，代码为 rate_limited，并附带以秒为单位的 retry_after。

安全重试：Idempotency-Key

在发送 POST、PUT、PATCH 和 DELETE 请求时，请附带 Idempotency-Key 请求头（一个 UUID）。如果连接中断，请使用相同的密钥重试：您将收到首次请求的响应，并附带 Idempotent-Replayed: true，域名不会被重复注册或重复扣费。成功的响应会按账户保留 24 小时；如果使用相同的密钥发送不同的请求，将被拒绝并返回 422 idempotency_key_reused。错误响应不会被保留，因此在排除原因（例如充值余额）后，使用相同的密钥重试将重新执行该请求。

curl

$ curl -X POST https://nameocean.net/api/v1/domains \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" -d '{"name": "example.com", "years": 1}'

Account

Account, credit and the activity log.

GET `/` #

Describe the API. Endpoints, record types, TTL values and scopes, as JSON.

权限范围: 无

curl

curl -X GET https://nameocean.net/api/v1/ \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

错误: 400 · 401 · 404 · 429

GET `/account` #

Account and credit. Your email and account credit in USD.

权限范围: account:read

curl

curl -X GET https://nameocean.net/api/v1/account \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`email`	string
`credit`	string	USD amount as a decimal string
`currency`	"USD"
`domains`	integer
`dns_zones`	integer
`add_funds_url`	string

错误: 400 · 401 · 403 · 404 · 429

GET `/audit` #

Activity log. What was done on the account through the API, the CLI and MCP (every write call, refused calls and transfer-code reads) and API key and app changes in the dashboard. Newest first; pass next_cursor as cursor for the next page.

权限范围: account:read

参数	位置	描述
`limit`	query
`cursor`	query	next_cursor from the previous page
`channel`	query

curl

curl -X GET https://nameocean.net/api/v1/audit?limit=1&cursor=1&channel=1 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`events`	AuditEvent[]
`next_cursor`	string \| null

错误: 400 · 401 · 403 · 404 · 429

Domains

Search, register, renew and manage domains.

GET `/domains/check` #

Check availability and price. Is a domain free to register, and what it costs.

权限范围: domains:read

参数	位置	描述
`name` *	query	例如 example.com
`years`	query

curl

curl -X GET https://nameocean.net/api/v1/domains/check?name=example.com&years=1 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`name`	string
`available`	boolean
`reason`	string	Why it is not available.
`years`	integer
`premium`	boolean
`register_price`	string	USD amount as a decimal string
`renew_price`	string	USD amount as a decimal string
`currency`	"USD"

错误: 400 · 401 · 403 · 404 · 429

GET `/domains` #

List domains

权限范围: domains:read

curl

curl -X GET https://nameocean.net/api/v1/domains \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domains`	Domain[]

错误: 400 · 401 · 403 · 404 · 429

POST `/domains` #

Register a domain. Paid from account credit; 402 with code insufficient_credit when it is not enough. Premium names need accept_premium: true. Send an Idempotency-Key so a retry never registers twice.

权限范围: domains:write billing:write · Idempotency-Key

请求体字段	类型	描述
`name` *	string
`years`	integer
`accept_premium`	boolean

curl

curl -X POST https://nameocean.net/api/v1/domains \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com", "years": 1}'

201 Registered; its DNS zone is returned.

响应字段	类型	描述
`name`	string
`records`	Record[]
`hint`	string

错误: 400 · 401 · 402 · 403 · 404 · 429

GET `/domains/{name}` #

Get a domain. Nameservers, lock, auto-renew and SSL status.

权限范围: domains:read

参数	位置	描述
`name` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/domains/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`name`	string
`active`	boolean
`pending`	boolean
`suspended`	boolean
`expires_on`	string \| null
`auto_renew`	boolean
`locked`	boolean
`created_at`	string \| null
`renewal_price`	string \| null
`nameservers`	string[]
`custom_nameservers`	boolean
`dns_zone`	boolean
`ssl`	Ssl

错误: 400 · 401 · 403 · 404 · 429

PATCH `/domains/{name}` #

Change auto-renew or lock

权限范围: domains:write · Idempotency-Key

参数	位置	描述
`name` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`auto_renew`	boolean
`locked`	boolean

curl

curl -X PATCH https://nameocean.net/api/v1/domains/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew": true}'

200 OK

响应字段	类型	描述
`name`	string
`active`	boolean
`pending`	boolean
`suspended`	boolean
`expires_on`	string \| null
`auto_renew`	boolean
`locked`	boolean
`created_at`	string \| null
`renewal_price`	string \| null
`nameservers`	string[]
`custom_nameservers`	boolean
`dns_zone`	boolean
`ssl`	Ssl

错误: 400 · 401 · 403 · 404 · 429

PUT `/domains/{name}/nameservers` #

Set nameservers. Two to four hostnames, or "nameocean" for NameOcean DNS.

权限范围: domains:write · Idempotency-Key

参数	位置	描述
`name` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`nameservers` *	array \| string

curl

curl -X PUT https://nameocean.net/api/v1/domains/example.com/nameservers \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nameservers": ["ns1.example.net", "ns2.example.net"]}'

200 OK

响应字段	类型	描述
`name`	string
`active`	boolean
`pending`	boolean
`suspended`	boolean
`expires_on`	string \| null
`auto_renew`	boolean
`locked`	boolean
`created_at`	string \| null
`renewal_price`	string \| null
`nameservers`	string[]
`custom_nameservers`	boolean
`dns_zone`	boolean
`ssl`	Ssl

错误: 400 · 401 · 403 · 404 · 429

POST `/domains/{name}/renew` #

Renew one year. Paid from account credit, within 60 days of expiry. Send an Idempotency-Key.

权限范围: domains:write billing:write · Idempotency-Key

参数	位置	描述
`name` *	path	Domain name 例如 example.com

curl

curl -X POST https://nameocean.net/api/v1/domains/example.com/renew \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`renewed`	string
`charged`	string	USD amount as a decimal string
`credit`	string	USD amount as a decimal string

错误: 400 · 401 · 402 · 403 · 404 · 429

GET `/domains/{name}/auth-code` #

Get the transfer code. The EPP code to move the domain away.

权限范围: domains:write

参数	位置	描述
`name` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/domains/example.com/auth-code \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`name`	string
`auth_code`	string

错误: 400 · 401 · 403 · 404 · 429

DNS

Zones and records.

GET `/dns` #

List DNS zones

权限范围: dns:read

curl

curl -X GET https://nameocean.net/api/v1/dns \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`zones`	object[]

错误: 400 · 401 · 403 · 404 · 429

POST `/dns` #

Create a DNS zone. Free. Point the domain's nameservers to ns1-ns4.nameocean.net to use it.

权限范围: dns:write · Idempotency-Key

请求体字段	类型	描述
`name` *	string

curl

curl -X POST https://nameocean.net/api/v1/dns \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}'

201 Created

响应字段	类型	描述
`name`	string
`records`	Record[]
`hint`	string

错误: 400 · 401 · 403 · 404 · 429

GET `/dns/{zone}/records` #

List records

权限范围: dns:read

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/dns/example.com/records \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`zone`	string
`records`	Record[]

错误: 400 · 401 · 403 · 404 · 429

POST `/dns/{zone}/records` #

Add a record

权限范围: dns:write · Idempotency-Key

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com

请求体字段	类型	描述
`type` *	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname` *	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

curl

curl -X POST https://nameocean.net/api/v1/dns/example.com/records \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "A", "hostname": "@", "ip": "203.0.113.10", "ttl": "1h"}'

201 Created

响应字段	类型	描述
`id`	integer
`type`	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname`	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

错误: 400 · 401 · 403 · 404 · 429

GET `/dns/{zone}/records/{type}/{id}` #

Get a record

权限范围: dns:read

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT 例如 A
`id` *	path	Numeric id 例如 42

curl

curl -X GET https://nameocean.net/api/v1/dns/example.com/records/A/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	integer
`type`	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname`	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

错误: 400 · 401 · 403 · 404 · 429

PATCH `/dns/{zone}/records/{type}/{id}` #

Change a record. Send only the fields to change.

权限范围: dns:write · Idempotency-Key

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT 例如 A
`id` *	path	Numeric id 例如 42

请求体字段	类型	描述
`type` *	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname` *	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

curl

curl -X PATCH https://nameocean.net/api/v1/dns/example.com/records/A/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.20"}'

200 OK

响应字段	类型	描述
`id`	integer
`type`	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname`	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

错误: 400 · 401 · 403 · 404 · 429

PUT `/dns/{zone}/records/{type}/{id}` #

Replace a record. Same as PATCH.

权限范围: dns:write · Idempotency-Key

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT 例如 A
`id` *	path	Numeric id 例如 42

请求体字段	类型	描述
`type` *	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname` *	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

curl

curl -X PUT https://nameocean.net/api/v1/dns/example.com/records/A/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	integer
`type`	string	One of: A, CNAME, MX, TXT, SRV, PTR, REDIRECT
`hostname`	string	@ for the zone itself
`ip`	string	A (IPv4 or IPv6)
`target`	string	CNAME, MX, SRV, PTR, REDIRECT
`text`	string	TXT
`priority`	integer	MX, SRV
`weight`	integer	SRV
`port`	integer	SRV
`save_path`	boolean	REDIRECT: keep the path
`ttl`	string	One of: 5m, 15m, 30m, 1h, 1d

错误: 400 · 401 · 403 · 404 · 429

DELETE `/dns/{zone}/records/{type}/{id}` #

Delete a record

权限范围: dns:write · Idempotency-Key

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT 例如 A
`id` *	path	Numeric id 例如 42

curl

curl -X DELETE https://nameocean.net/api/v1/dns/example.com/records/A/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

SSL

Free wildcard certificates.

GET `/ssl/{zone}` #

Certificate status

权限范围: ssl:read

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/ssl/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

错误: 400 · 401 · 403 · 404 · 429

POST `/ssl/{zone}` #

Issue a certificate. Free wildcard Let's Encrypt certificate; the zone must use NameOcean nameservers. Poll GET until active.

权限范围: ssl:write · Idempotency-Key

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com

curl

curl -X POST https://nameocean.net/api/v1/ssl/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

202 Issuing

响应字段	类型	描述
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

错误: 400 · 401 · 403 · 404 · 429

PATCH `/ssl/{zone}` #

Change auto-renew

权限范围: ssl:write · Idempotency-Key

参数	位置	描述
`zone` *	path	DNS zone (domain) name 例如 example.com

请求体字段	类型	描述
`auto_renew` *	boolean

curl

curl -X PATCH https://nameocean.net/api/v1/ssl/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew": true}'

200 OK

响应字段	类型	描述
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

错误: 400 · 401 · 403 · 404 · 429

Servers

App servers: ports and domain bindings.

GET `/servers` #

List app servers

权限范围: servers:read

curl

curl -X GET https://nameocean.net/api/v1/servers \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`servers`	Server[]

错误: 400 · 401 · 403 · 404 · 429

GET `/servers/{server}` #

Get a server. SSH, git remote, ports and domains.

权限范围: servers:read

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e

curl

curl -X GET https://nameocean.net/api/v1/servers/3f9a1c2e \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	integer
`name`	string
`status`	string
`plan`	string \| null
`default_domain`	string
`cpu`	integer
`memory_mb`	integer
`disk_gb`	integer
`private_ip`	string \| null
`ipv6`	string \| null
`ssh`	object
`git_remote`	string \| null
`backups`	boolean
`ports`	Port[]
`domains`	Binding[]

错误: 400 · 401 · 403 · 404 · 429

GET `/servers/{server}/ports` #

List open ports

权限范围: servers:read

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e

curl

curl -X GET https://nameocean.net/api/v1/servers/3f9a1c2e/ports \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`server`	string
`ports`	Port[]

错误: 400 · 401 · 403 · 404 · 429

POST `/servers/{server}/ports` #

Open a port. The external port is assigned.

权限范围: servers:write · Idempotency-Key

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e

请求体字段	类型	描述
`port` *	integer
`protocol`	string	One of: tcp, udp

curl

curl -X POST https://nameocean.net/api/v1/servers/3f9a1c2e/ports \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 25565, "protocol": "tcp"}'

201 Opened

响应字段	类型	描述
`id`	integer
`protocol`	string	One of: tcp, udp
`internal_port`	integer
`external_port`	integer
`connect_to`	string	Only when the port was just opened.

错误: 400 · 401 · 403 · 404 · 429

DELETE `/servers/{server}/ports/{id}` #

Close a port

权限范围: servers:write · Idempotency-Key

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e
`id` *	path	Numeric id 例如 42

curl

curl -X DELETE https://nameocean.net/api/v1/servers/3f9a1c2e/ports/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Closed

错误: 400 · 401 · 403 · 404 · 429

GET `/servers/{server}/domains` #

List bound domains

权限范围: servers:read

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e

curl

curl -X GET https://nameocean.net/api/v1/servers/3f9a1c2e/domains \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`server`	string
`domains`	Binding[]

错误: 400 · 401 · 403 · 404 · 429

POST `/servers/{server}/domains` #

Bind a domain. Serves a domain or subdomain from the server: DNS records, SSL and the load balancer. Poll GET until status is active.

权限范围: servers:write dns:write · Idempotency-Key

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e

请求体字段	类型	描述
`domain` *	string
`subdomain`	string

curl

curl -X POST https://nameocean.net/api/v1/servers/3f9a1c2e/domains \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.example.com"}'

201 Setting up

响应字段	类型	描述
`id`	integer
`domain`	string
`status`	string	One of: setting_up, active
`url`	string

错误: 400 · 401 · 403 · 404 · 429

DELETE `/servers/{server}/domains/{id}` #

Unbind a domain

权限范围: servers:write dns:write · Idempotency-Key

参数	位置	描述
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org 例如 3f9a1c2e
`id` *	path	Numeric id 例如 42

curl

curl -X DELETE https://nameocean.net/api/v1/servers/3f9a1c2e/domains/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Unbound

错误: 400 · 401 · 403 · 404 · 429

Email hosting

Mailboxes, aliases and mailing lists on your paid mail domains (Mox).

GET `/email/domains` #

List mail domains. Domains with paid email hosting. Buying, upgrading and reactivating a plan is done in the dashboard.

权限范围: email:read

curl

curl -X GET https://nameocean.net/api/v1/email/domains \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domains`	MailDomain[]

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}` #

Get a mail domain. With its mailboxes, aliases, mailing lists and the IMAP/SMTP settings.

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`active`	boolean
`suspended_reason`	string \| null	One of: unpaid, ended, admin, None
`plan`	string \| null
`storage_gb`	integer
`used_gb`	string	Decimal GB, as of the last refresh
`assigned_gb`	integer	Sum of the mailboxes' quotas (at most storage_gb)
`max_mailboxes`	integer \| null
`mailbox_count`	integer
`expires_at`	string \| null
`auto_renew`	boolean
`dashboard`	string
`mailboxes`	Mailbox[]	Only on GET /email/domains/{domain}
`aliases`	MailAlias[]
`lists`	MailingList[]
`settings`	object	IMAP, SMTP and webmail for mail clients

错误: 400 · 401 · 403 · 404 · 429

PATCH `/email/domains/{domain}` #

Change mail auto-renew

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`auto_renew` *	boolean

curl

curl -X PATCH https://nameocean.net/api/v1/email/domains/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew": true}'

200 OK

响应字段	类型	描述
`domain`	string
`active`	boolean
`suspended_reason`	string \| null	One of: unpaid, ended, admin, None
`plan`	string \| null
`storage_gb`	integer
`used_gb`	string	Decimal GB, as of the last refresh
`assigned_gb`	integer	Sum of the mailboxes' quotas (at most storage_gb)
`max_mailboxes`	integer \| null
`mailbox_count`	integer
`expires_at`	string \| null
`auto_renew`	boolean
`dashboard`	string
`mailboxes`	Mailbox[]	Only on GET /email/domains/{domain}
`aliases`	MailAlias[]
`lists`	MailingList[]
`settings`	object	IMAP, SMTP and webmail for mail clients

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}/dns-check` #

Check mail DNS. Looks up NS, MX, SPF, DKIM and DMARC now and compares them with what NameOcean mail needs.

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com/dns-check \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`ok`	boolean
`checks`	object	ns, mx, spf, dkim, dmarc

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}/mailboxes` #

List mailboxes

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com/mailboxes \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`mailboxes`	Mailbox[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/domains/{domain}/mailboxes` #

Create a mailbox. Without a password one is generated. The answer is the only time the password is returned. quota_gb comes out of the plan's storage (default 1).

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`username` *	string
`full_name`	string
`password`	string
`quota_gb`	integer

curl

curl -X POST https://nameocean.net/api/v1/email/domains/example.com/mailboxes \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "info", "full_name": "Info"}'

201 Created

响应字段	类型	描述
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}/mailboxes/{username}` #

Get a mailbox

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`username` *	path	Mailbox name, the part before @ (or the full address) 例如 info

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com/mailboxes/info \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

错误: 400 · 401 · 403 · 404 · 429

PATCH `/email/domains/{domain}/mailboxes/{username}` #

Change a mailbox. Send only what changes.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`username` *	path	Mailbox name, the part before @ (or the full address) 例如 info

请求体字段	类型	描述
`full_name`	string
`quota_gb`	integer

curl

curl -X PATCH https://nameocean.net/api/v1/email/domains/example.com/mailboxes/info \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quota_gb": 5}'

200 OK

响应字段	类型	描述
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

错误: 400 · 401 · 403 · 404 · 429

DELETE `/email/domains/{domain}/mailboxes/{username}` #

Delete a mailbox. Deletes the mailbox, all its mail and its aliases. This can't be undone.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`username` *	path	Mailbox name, the part before @ (or the full address) 例如 info

curl

curl -X DELETE https://nameocean.net/api/v1/email/domains/example.com/mailboxes/info \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

POST `/email/domains/{domain}/mailboxes/{username}/password` #

Set a mailbox password. Sets the password you send, or generates one when you send none, and returns it.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`username` *	path	Mailbox name, the part before @ (or the full address) 例如 info

请求体字段	类型	描述
`password`	string

curl

curl -X POST https://nameocean.net/api/v1/email/domains/example.com/mailboxes/info/password \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 OK

响应字段	类型	描述
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}/aliases` #

List mail aliases

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com/aliases \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`aliases`	MailAlias[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/domains/{domain}/aliases` #

Add a mail alias. Mail to alias is delivered to the mailbox. Both are on the same domain; send the full address or the part before @.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`alias` *	string
`mailbox` *	string

curl

curl -X POST https://nameocean.net/api/v1/email/domains/example.com/aliases \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias": "sales", "mailbox": "info"}'

201 Created

响应字段	类型	描述
`address`	string
`mailbox`	string	The mailbox that receives it

错误: 400 · 401 · 403 · 404 · 429

DELETE `/email/domains/{domain}/aliases/{alias}` #

Delete a mail alias

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`alias` *	path	Alias address, or the part before @ 例如 sales

curl

curl -X DELETE https://nameocean.net/api/v1/email/domains/example.com/aliases/sales \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}/lists` #

List mailing lists

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com/lists \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`lists`	MailingList[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/domains/{domain}/lists` #

Create a mailing list. Mail to the list's address goes to every member (mailboxes of the domain).

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`address` *	string
`name`	string
`members`	string[]

curl

curl -X POST https://nameocean.net/api/v1/email/domains/example.com/lists \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "team", "members": ["info", "sales"]}'

201 Created

响应字段	类型	描述
`address`	string
`name`	string
`members`	string[]

错误: 400 · 401 · 403 · 404 · 429

GET `/email/domains/{domain}/lists/{address}` #

Get a mailing list

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`address` *	path	Mailing list address, or the part before @ 例如 team

curl

curl -X GET https://nameocean.net/api/v1/email/domains/example.com/lists/team \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`address`	string
`name`	string
`members`	string[]

错误: 400 · 401 · 403 · 404 · 429

PATCH `/email/domains/{domain}/lists/{address}` #

Change a mailing list. members replaces the whole member list.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`address` *	path	Mailing list address, or the part before @ 例如 team

请求体字段	类型	描述
`name`	string
`members`	string[]

curl

curl -X PATCH https://nameocean.net/api/v1/email/domains/example.com/lists/team \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"members": ["info"]}'

200 OK

响应字段	类型	描述
`address`	string
`name`	string
`members`	string[]

错误: 400 · 401 · 403 · 404 · 429

DELETE `/email/domains/{domain}/lists/{address}` #

Delete a mailing list

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`address` *	path	Mailing list address, or the part before @ 例如 team

curl

curl -X DELETE https://nameocean.net/api/v1/email/domains/example.com/lists/team \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

Email forwarding

Free forwarding and mail-to-webhook for domains registered at NameOcean.

GET `/email/forwarding` #

List forwarding domains. Every active domain registered in your account, with whether forwarding is on and, when off, why it can't be.

权限范围: email:read

curl

curl -X GET https://nameocean.net/api/v1/email/forwarding \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domains`	Forwarding[]

错误: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/{domain}` #

Get forwarding. Aliases and mail webhooks.

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/forwarding/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`active`	boolean
`disabled_reason`	string \| null
`problems`	string[]	Why it can't be turned on, when it is off
`alias_count`	integer
`webhook_count`	integer
`mx`	string	The MX host forwarding writes into the zone
`max_aliases`	integer
`max_webhooks`	integer
`daily_limit`	integer	Mails forwarded per domain and day
`aliases`	ForwardAlias[]
`webhooks`	MailWebhook[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/{domain}` #

Turn forwarding on. Free for domains registered at NameOcean that use NameOcean nameservers. Writes the MX record; other MX records are removed only with replace_mx: true (otherwise 409 mx_records_exist).

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`replace_mx`	boolean

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replace_mx": false}'

200 OK

响应字段	类型	描述
`domain`	string
`active`	boolean
`disabled_reason`	string \| null
`problems`	string[]	Why it can't be turned on, when it is off
`alias_count`	integer
`webhook_count`	integer
`mx`	string	The MX host forwarding writes into the zone
`max_aliases`	integer
`max_webhooks`	integer
`daily_limit`	integer	Mails forwarded per domain and day
`aliases`	ForwardAlias[]
`webhooks`	MailWebhook[]

错误: 400 · 401 · 403 · 404 · 429

DELETE `/email/forwarding/{domain}` #

Turn forwarding off. Removes the MX record; aliases are kept for when it is turned on again.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X DELETE https://nameocean.net/api/v1/email/forwarding/example.com \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Turned off

错误: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/{domain}/aliases` #

List forwarding aliases

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/forwarding/example.com/aliases \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`aliases`	ForwardAlias[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/{domain}/aliases` #

Add a forwarding alias. localpart@domain forwards to `to`; * forwards every address without its own alias. An address not confirmed yet gets a mail with a link and a code; mail is forwarded once it is confirmed.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`localpart` *	string
`to` *	string

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/aliases \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localpart": "hello", "to": "me@gmail.com"}'

201 Created

响应字段	类型	描述
`localpart`	string	* = every address without its own alias
`address`	string
`catch_all`	boolean
`to`	string
`to_status`	string	One of: pending, confirmed, refused
`active`	boolean
`note`	string	Only when just added: what happens next

错误: 400 · 401 · 403 · 404 · 429

DELETE `/email/forwarding/{domain}/aliases/{localpart}` #

Delete a forwarding alias. Use * (%2A) for the catch-all.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all 例如 hello

curl

curl -X DELETE https://nameocean.net/api/v1/email/forwarding/example.com/aliases/hello \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/targets` #

List forwarding targets. Addresses you forward to and whether they confirmed.

权限范围: email:read

curl

curl -X GET https://nameocean.net/api/v1/email/forwarding/targets \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`targets`	ForwardTarget[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/targets/{id}/verify` #

Confirm a forwarding target. The 6-digit code from the confirmation mail.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`id` *	path	Numeric id 例如 42

请求体字段	类型	描述
`code` *	string

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/targets/42/verify \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

200 OK

响应字段	类型	描述
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/targets/{id}/resend` #

Resend a confirmation code. At most 3 a day per address.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`id` *	path	Numeric id 例如 42

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/targets/42/resend \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

错误: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/{domain}/messages` #

List forwarded mail. The last 30 days, newest first: headers and what happened, never the body.

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`limit`	query
`cursor`	query
`status`	query

curl

curl -X GET https://nameocean.net/api/v1/email/forwarding/example.com/messages?limit=1&cursor=1&status=1 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`messages`	ForwardedMessage[]
`next_cursor`	string \| null

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/{domain}/messages/{message_id}/release` #

Forward held mail. Forwards a message held as spam, over the daily limit or failed (releasable: true).

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`message_id` *	path	Message id (uuid) 例如 6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/messages/6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f/release \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

202 Forwarding

响应字段	类型	描述
`id`	string
`received_at`	string \| null
`to`	string
`forwarded_to`	string \| null
`from`	string \| null
`subject`	string \| null
`size`	integer
`status`	string	One of: forwarded, spam, quota, release_requested, released, bounced, loop, failed
`spam_score`	number \| null
`releasable`	boolean
`smtp_response`	string \| null

错误: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/{domain}/webhooks` #

List mail webhooks. Addresses whose mail is posted to your URL as JSON, with their signing secrets.

权限范围: email:read

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

curl

curl -X GET https://nameocean.net/api/v1/email/forwarding/example.com/webhooks \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`domain`	string
`webhooks`	MailWebhook[]

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/{domain}/webhooks` #

Add a mail webhook. Mail to localpart@domain is posted to url as JSON (an email.received event). Open after a short review (403 not_approved until then); ask for it in the dashboard.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com

请求体字段	类型	描述
`localpart` *	string
`url` *	string

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/webhooks \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localpart": "inbound", "url": "https://example.com/hooks/mail"}'

201 Created

响应字段	类型	描述
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

错误: 400 · 401 · 403 · 404 · 429

DELETE `/email/forwarding/{domain}/webhooks/{localpart}` #

Delete a mail webhook

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all 例如 hello

curl

curl -X DELETE https://nameocean.net/api/v1/email/forwarding/example.com/webhooks/hello \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

POST `/email/forwarding/{domain}/webhooks/{localpart}/rotate-secret` #

Rotate a mail webhook secret. The old secret stops working at once.

权限范围: email:write · Idempotency-Key

参数	位置	描述
`domain` *	path	Domain name 例如 example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all 例如 hello

curl

curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com/webhooks/hello/rotate-secret \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

错误: 400 · 401 · 403 · 404 · 429

Webhooks

Endpoints that receive account events: https://nameocean.net/developers/webhooks/

GET `/webhooks/events` #

List event types. Every event type and group you can subscribe to.

权限范围: webhooks:read

curl

curl -X GET https://nameocean.net/api/v1/webhooks/events \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`events`	object[]
`groups`	string[]

错误: 400 · 401 · 403 · 404 · 429

GET `/webhooks` #

List webhook endpoints

权限范围: webhooks:read

curl

curl -X GET https://nameocean.net/api/v1/webhooks \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`webhooks`	WebhookEndpoint[]

错误: 400 · 401 · 403 · 404 · 429

POST `/webhooks` #

Add a webhook endpoint. An https URL on a public server. The answer includes the signing secret. Up to 10 endpoints.

权限范围: webhooks:write · Idempotency-Key

请求体字段	类型	描述
`url` *	string
`events` *	string[]
`description`	string

curl

curl -X POST https://nameocean.net/api/v1/webhooks \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/nameocean", "events": ["dns.*", "ssl.issued"]}'

201 Created

响应字段	类型	描述
`id`	integer
`url`	string
`description`	string
`events`	string[]	Event types, groups like "dns.", or [""]
`active`	boolean
`disabled_reason`	string \| null	Why NameOcean turned it off
`secret`	string	whsec_...: verify X-NameOcean-Signature with it. Not in list answers.
`created_at`	string \| null
`last_success_at`	string \| null
`last_failure_at`	string \| null

错误: 400 · 401 · 403 · 404 · 429

GET `/webhooks/{id}` #

Get a webhook endpoint. With its signing secret.

权限范围: webhooks:read

参数	位置	描述
`id` *	path	Numeric id 例如 42

curl

curl -X GET https://nameocean.net/api/v1/webhooks/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	integer
`url`	string
`description`	string
`events`	string[]	Event types, groups like "dns.", or [""]
`active`	boolean
`disabled_reason`	string \| null	Why NameOcean turned it off
`secret`	string	whsec_...: verify X-NameOcean-Signature with it. Not in list answers.
`created_at`	string \| null
`last_success_at`	string \| null
`last_failure_at`	string \| null

错误: 400 · 401 · 403 · 404 · 429

PATCH `/webhooks/{id}` #

Change a webhook endpoint. Send only what changes. active: true turns a disabled endpoint back on.

权限范围: webhooks:write · Idempotency-Key

参数	位置	描述
`id` *	path	Numeric id 例如 42

请求体字段	类型	描述
`url`	string
`events`	string[]
`description`	string
`active`	boolean

curl

curl -X PATCH https://nameocean.net/api/v1/webhooks/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'

200 OK

响应字段	类型	描述
`id`	integer
`url`	string
`description`	string
`events`	string[]	Event types, groups like "dns.", or [""]
`active`	boolean
`disabled_reason`	string \| null	Why NameOcean turned it off
`secret`	string	whsec_...: verify X-NameOcean-Signature with it. Not in list answers.
`created_at`	string \| null
`last_success_at`	string \| null
`last_failure_at`	string \| null

错误: 400 · 401 · 403 · 404 · 429

DELETE `/webhooks/{id}` #

Delete a webhook endpoint

权限范围: webhooks:write · Idempotency-Key

参数	位置	描述
`id` *	path	Numeric id 例如 42

curl

curl -X DELETE https://nameocean.net/api/v1/webhooks/42 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

204 Deleted

错误: 400 · 401 · 403 · 404 · 429

POST `/webhooks/{id}/test` #

Send a test event. Posts a webhook.test event now, whatever the endpoint's event filter, and returns the delivery.

权限范围: webhooks:write · Idempotency-Key

参数	位置	描述
`id` *	path	Numeric id 例如 42

curl

curl -X POST https://nameocean.net/api/v1/webhooks/42/test \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	string	whd_..., also sent as X-NameOcean-Delivery
`event`	object
`status`	string	One of: pending, succeeded, failed
`attempts`	integer
`next_attempt_at`	string \| null
`last_attempt_at`	string \| null
`response_status`	integer \| null
`response_body`	string \| null	First 500 characters
`error`	string \| null

错误: 400 · 401 · 403 · 404 · 429

GET `/webhooks/{id}/deliveries` #

List deliveries. Newest first; pass next_cursor as cursor for the next page.

权限范围: webhooks:read

参数	位置	描述
`id` *	path	Numeric id 例如 42
`limit`	query
`cursor`	query
`status`	query

curl

curl -X GET https://nameocean.net/api/v1/webhooks/42/deliveries?limit=1&cursor=1&status=1 \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`deliveries`	WebhookDelivery[]
`next_cursor`	string \| null

错误: 400 · 401 · 403 · 404 · 429

POST `/webhooks/{id}/deliveries/{delivery_id}/resend` #

Resend a delivery. Posts the same event (same id) again now.

权限范围: webhooks:write · Idempotency-Key

参数	位置	描述
`id` *	path	Numeric id 例如 42
`delivery_id` *	path	Delivery id (whd_...) 例如 whd_3f9a1c2e4b5d6a7c8e9f0a1b

curl

curl -X POST https://nameocean.net/api/v1/webhooks/42/deliveries/whd_3f9a1c2e4b5d6a7c8e9f0a1b/resend \
  -H "Authorization: Bearer $NAMEOCEAN_API_KEY"

200 OK

响应字段	类型	描述
`id`	string	whd_..., also sent as X-NameOcean-Delivery
`event`	object
`status`	string	One of: pending, succeeded, failed
`attempts`	integer
`next_attempt_at`	string \| null
`last_attempt_at`	string \| null
`response_status`	integer \| null
`response_body`	string \| null	First 500 characters
`error`	string \| null

错误: 400 · 401 · 403 · 404 · 429

REST API 参考文档

基础 URL

身份验证

OpenAPI 3.1

权限范围

错误

速率限制

安全重试：Idempotency-Key

Account

GET / #

GET /account #

GET /audit #

Domains

GET /domains/check #

GET /domains #

POST /domains #

GET /domains/{name} #

PATCH /domains/{name} #

PUT /domains/{name}/nameservers #

POST /domains/{name}/renew #

GET /domains/{name}/auth-code #

DNS

GET /dns #

POST /dns #

GET /dns/{zone}/records #

POST /dns/{zone}/records #

GET /dns/{zone}/records/{type}/{id} #

PATCH /dns/{zone}/records/{type}/{id} #

PUT /dns/{zone}/records/{type}/{id} #

DELETE /dns/{zone}/records/{type}/{id} #

SSL

GET /ssl/{zone} #

POST /ssl/{zone} #

PATCH /ssl/{zone} #

Servers

GET /servers #

GET /servers/{server} #

GET /servers/{server}/ports #

POST /servers/{server}/ports #

DELETE /servers/{server}/ports/{id} #

GET /servers/{server}/domains #

POST /servers/{server}/domains #

DELETE /servers/{server}/domains/{id} #

Email hosting

GET /email/domains #

GET /email/domains/{domain} #

PATCH /email/domains/{domain} #

GET /email/domains/{domain}/dns-check #

GET /email/domains/{domain}/mailboxes #

POST /email/domains/{domain}/mailboxes #

GET /email/domains/{domain}/mailboxes/{username} #

PATCH /email/domains/{domain}/mailboxes/{username} #

DELETE /email/domains/{domain}/mailboxes/{username} #

POST /email/domains/{domain}/mailboxes/{username}/password #

GET /email/domains/{domain}/aliases #

POST /email/domains/{domain}/aliases #

DELETE /email/domains/{domain}/aliases/{alias} #

GET /email/domains/{domain}/lists #

POST /email/domains/{domain}/lists #

GET /email/domains/{domain}/lists/{address} #

PATCH /email/domains/{domain}/lists/{address} #

DELETE /email/domains/{domain}/lists/{address} #

Email forwarding

GET /email/forwarding #

GET /email/forwarding/{domain} #

POST /email/forwarding/{domain} #

DELETE /email/forwarding/{domain} #

GET /email/forwarding/{domain}/aliases #

POST /email/forwarding/{domain}/aliases #

DELETE /email/forwarding/{domain}/aliases/{localpart} #

GET /email/forwarding/targets #

POST /email/forwarding/targets/{id}/verify #

POST /email/forwarding/targets/{id}/resend #

GET /email/forwarding/{domain}/messages #

POST /email/forwarding/{domain}/messages/{message_id}/release #

GET /email/forwarding/{domain}/webhooks #

POST /email/forwarding/{domain}/webhooks #

DELETE /email/forwarding/{domain}/webhooks/{localpart} #

POST /email/forwarding/{domain}/webhooks/{localpart}/rotate-secret #

Webhooks

GET `/` #

GET `/account` #

GET `/audit` #

GET `/domains/check` #

GET `/domains` #

POST `/domains` #

GET `/domains/{name}` #

PATCH `/domains/{name}` #

PUT `/domains/{name}/nameservers` #

POST `/domains/{name}/renew` #

GET `/domains/{name}/auth-code` #

GET `/dns` #

POST `/dns` #

GET `/dns/{zone}/records` #

POST `/dns/{zone}/records` #

GET `/dns/{zone}/records/{type}/{id}` #

PATCH `/dns/{zone}/records/{type}/{id}` #

PUT `/dns/{zone}/records/{type}/{id}` #

DELETE `/dns/{zone}/records/{type}/{id}` #

GET `/ssl/{zone}` #

POST `/ssl/{zone}` #

PATCH `/ssl/{zone}` #

GET `/servers` #

GET `/servers/{server}` #

GET `/servers/{server}/ports` #

POST `/servers/{server}/ports` #

DELETE `/servers/{server}/ports/{id}` #

GET `/servers/{server}/domains` #

POST `/servers/{server}/domains` #

DELETE `/servers/{server}/domains/{id}` #

GET `/email/domains` #

GET `/email/domains/{domain}` #

PATCH `/email/domains/{domain}` #

GET `/email/domains/{domain}/dns-check` #

GET `/email/domains/{domain}/mailboxes` #

POST `/email/domains/{domain}/mailboxes` #

GET `/email/domains/{domain}/mailboxes/{username}` #

PATCH `/email/domains/{domain}/mailboxes/{username}` #

DELETE `/email/domains/{domain}/mailboxes/{username}` #

POST `/email/domains/{domain}/mailboxes/{username}/password` #

GET `/email/domains/{domain}/aliases` #

POST `/email/domains/{domain}/aliases` #

DELETE `/email/domains/{domain}/aliases/{alias}` #

GET `/email/domains/{domain}/lists` #

POST `/email/domains/{domain}/lists` #

GET `/email/domains/{domain}/lists/{address}` #

PATCH `/email/domains/{domain}/lists/{address}` #

DELETE `/email/domains/{domain}/lists/{address}` #

GET `/email/forwarding` #

GET `/email/forwarding/{domain}` #

POST `/email/forwarding/{domain}` #

DELETE `/email/forwarding/{domain}` #

GET `/email/forwarding/{domain}/aliases` #

POST `/email/forwarding/{domain}/aliases` #

DELETE `/email/forwarding/{domain}/aliases/{localpart}` #

GET `/email/forwarding/targets` #

POST `/email/forwarding/targets/{id}/verify` #

POST `/email/forwarding/targets/{id}/resend` #

GET `/email/forwarding/{domain}/messages` #

POST `/email/forwarding/{domain}/messages/{message_id}/release` #

GET `/email/forwarding/{domain}/webhooks` #

POST `/email/forwarding/{domain}/webhooks` #

DELETE `/email/forwarding/{domain}/webhooks/{localpart}` #

POST `/email/forwarding/{domain}/webhooks/{localpart}/rotate-secret` #

GET `/webhooks/events` #

GET `/webhooks` #

POST `/webhooks` #

GET `/webhooks/{id}` #

PATCH `/webhooks/{id}` #

DELETE `/webhooks/{id}` #

POST `/webhooks/{id}/test` #

GET `/webhooks/{id}/deliveries` #

POST `/webhooks/{id}/deliveries/{delivery_id}/resend` #