Sviluppatori → REST API

Riferimento API REST

Domini, DNS, SSL e server applicativi via HTTPS. JSON in ingresso, JSON in uscita, un unico URL di base.

URL di base

https://nameocean.net/api/v1

Autenticazione

Authorization: Bearer <key> con una chiave da Dashboard → Chiavi API.

OpenAPI 3.1

/api/v1/openapi.json · lo importi in Postman, Insomnia o Bruno, oppure generi un client.

Ambiti

Ogni chiave ha dei permessi. GET richiede <area>:read, gli altri metodi <area>:write; ogni endpoint qui sotto indica cosa richiede. In mancanza, la risposta è 403 con codice missing_scope e required_scopes. Tutti gli ambiti.

Errori

Ogni errore ha la stessa struttura: un messaggio scritto per persone e agenti AI, e un codice stabile su cui basare la logica. field indica l'input errato, quando presente.

HTTP 400

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

Codici: 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

Limiti di frequenza

120 richieste al minuto per account. Ogni risposta include X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi prima che si liberi uno slot). Oltre il limite la risposta è 429 con codice rate_limited e retry_after in secondi.

Ritentare in sicurezza: Idempotency-Key

Inviate un header Idempotency-Key (un UUID) con le richieste POST, PUT, PATCH e DELETE. Se la connessione si interrompe, riprovate con la stessa chiave: riceverete la prima risposta con Idempotent-Replayed: true e il dominio non verrà registrato né addebitato due volte. Le risposte andate a buon fine vengono conservate per 24 ore per ciascun account; la stessa chiave usata con una richiesta diversa viene rifiutata con 422 idempotency_key_reused. Gli errori non vengono conservati, quindi dopo averne risolto la causa (ad esempio aggiungendo credito) un nuovo tentativo con la stessa chiave verrà eseguito di nuovo.

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.

Ambiti: nessuno

curl

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

200 OK

Errori: 400 · 401 · 404 · 429

GET `/account` #

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

Ambiti: account:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`email`	string
`credit`	string	USD amount as a decimal string
`currency`	"USD"
`domains`	integer
`dns_zones`	integer
`add_funds_url`	string

Errori: 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.

Ambiti: account:read

Parametro	In	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`events`	AuditEvent[]
`next_cursor`	string \| null

Errori: 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.

Ambiti: domains:read

Parametro	In	Descrizione
`name` *	query	es. 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

Campo della risposta	Tipo	Descrizione
`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"

Errori: 400 · 401 · 403 · 404 · 429

GET `/domains` #

List domains

Ambiti: domains:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domains`	Domain[]

Errori: 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.

Ambiti: domains:write billing:write · Idempotency-Key

Campo del body	Tipo	Descrizione
`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.

Campo della risposta	Tipo	Descrizione
`name`	string
`records`	Record[]
`hint`	string

Errori: 400 · 401 · 402 · 403 · 404 · 429

GET `/domains/{name}` #

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

Ambiti: domains:read

Parametro	In	Descrizione
`name` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

PATCH `/domains/{name}` #

Change auto-renew or lock

Ambiti: domains:write · Idempotency-Key

Parametro	In	Descrizione
`name` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: domains:write · Idempotency-Key

Parametro	In	Descrizione
`name` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 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.

Ambiti: domains:write billing:write · Idempotency-Key

Parametro	In	Descrizione
`name` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`renewed`	string
`charged`	string	USD amount as a decimal string
`credit`	string	USD amount as a decimal string

Errori: 400 · 401 · 402 · 403 · 404 · 429

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

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

Ambiti: domains:write

Parametro	In	Descrizione
`name` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`name`	string
`auth_code`	string

Errori: 400 · 401 · 403 · 404 · 429

DNS

Zones and records.

GET `/dns` #

List DNS zones

Ambiti: dns:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`zones`	object[]

Errori: 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.

Ambiti: dns:write · Idempotency-Key

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`name`	string
`records`	Record[]
`hint`	string

Errori: 400 · 401 · 403 · 404 · 429

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

List records

Ambiti: dns:read

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`zone`	string
`records`	Record[]

Errori: 400 · 401 · 403 · 404 · 429

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

Add a record

Ambiti: dns:write · Idempotency-Key

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

Get a record

Ambiti: dns:read

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT es. A
`id` *	path	Numeric id es. 42

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

Change a record. Send only the fields to change.

Ambiti: dns:write · Idempotency-Key

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT es. A
`id` *	path	Numeric id es. 42

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

Replace a record. Same as PATCH.

Ambiti: dns:write · Idempotency-Key

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT es. A
`id` *	path	Numeric id es. 42

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

Delete a record

Ambiti: dns:write · Idempotency-Key

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT es. A
`id` *	path	Numeric id es. 42

curl

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

204 Deleted

Errori: 400 · 401 · 403 · 404 · 429

SSL

Free wildcard certificates.

GET `/ssl/{zone}` #

Certificate status

Ambiti: ssl:read

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Errori: 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.

Ambiti: ssl:write · Idempotency-Key

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com

curl

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

202 Issuing

Campo della risposta	Tipo	Descrizione
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Errori: 400 · 401 · 403 · 404 · 429

PATCH `/ssl/{zone}` #

Change auto-renew

Ambiti: ssl:write · Idempotency-Key

Parametro	In	Descrizione
`zone` *	path	DNS zone (domain) name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Errori: 400 · 401 · 403 · 404 · 429

Servers

App servers: ports and domain bindings.

GET `/servers` #

List app servers

Ambiti: servers:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`servers`	Server[]

Errori: 400 · 401 · 403 · 404 · 429

GET `/servers/{server}` #

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

Ambiti: servers:read

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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[]

Errori: 400 · 401 · 403 · 404 · 429

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

List open ports

Ambiti: servers:read

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`server`	string
`ports`	Port[]

Errori: 400 · 401 · 403 · 404 · 429

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

Open a port. The external port is assigned.

Ambiti: servers:write · Idempotency-Key

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`id`	integer
`protocol`	string	One of: tcp, udp
`internal_port`	integer
`external_port`	integer
`connect_to`	string	Only when the port was just opened.

Errori: 400 · 401 · 403 · 404 · 429

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

Close a port

Ambiti: servers:write · Idempotency-Key

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e
`id` *	path	Numeric id es. 42

curl

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

204 Closed

Errori: 400 · 401 · 403 · 404 · 429

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

List bound domains

Ambiti: servers:read

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`server`	string
`domains`	Binding[]

Errori: 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.

Ambiti: servers:write dns:write · Idempotency-Key

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`id`	integer
`domain`	string
`status`	string	One of: setting_up, active
`url`	string

Errori: 400 · 401 · 403 · 404 · 429

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

Unbind a domain

Ambiti: servers:write dns:write · Idempotency-Key

Parametro	In	Descrizione
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org es. 3f9a1c2e
`id` *	path	Numeric id es. 42

curl

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

204 Unbound

Errori: 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.

Ambiti: email:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domains`	MailDomain[]

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

Change mail auto-renew

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 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.

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. 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

Campo della risposta	Tipo	Descrizione
`domain`	string
`ok`	boolean
`checks`	object	ns, mx, spf, dkim, dmarc

Errori: 400 · 401 · 403 · 404 · 429

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

List mailboxes

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domain`	string
`mailboxes`	Mailbox[]

Errori: 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).

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Errori: 400 · 401 · 403 · 404 · 429

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

Get a mailbox

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) es. info

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Errori: 400 · 401 · 403 · 404 · 429

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

Change a mailbox. Send only what changes.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) es. info

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Errori: 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.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) es. info

curl

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

204 Deleted

Errori: 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.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) es. info

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Errori: 400 · 401 · 403 · 404 · 429

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

List mail aliases

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domain`	string
`aliases`	MailAlias[]

Errori: 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 @.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`address`	string
`mailbox`	string	The mailbox that receives it

Errori: 400 · 401 · 403 · 404 · 429

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

Delete a mail alias

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`alias` *	path	Alias address, or the part before @ es. sales

curl

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

204 Deleted

Errori: 400 · 401 · 403 · 404 · 429

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

List mailing lists

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domain`	string
`lists`	MailingList[]

Errori: 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).

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`address`	string
`name`	string
`members`	string[]

Errori: 400 · 401 · 403 · 404 · 429

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

Get a mailing list

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`address` *	path	Mailing list address, or the part before @ es. team

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`address`	string
`name`	string
`members`	string[]

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`address` *	path	Mailing list address, or the part before @ es. team

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`address`	string
`name`	string
`members`	string[]

Errori: 400 · 401 · 403 · 404 · 429

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

Delete a mailing list

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`address` *	path	Mailing list address, or the part before @ es. team

curl

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

204 Deleted

Errori: 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.

Ambiti: email:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domains`	Forwarding[]

Errori: 400 · 401 · 403 · 404 · 429

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

Get forwarding. Aliases and mail webhooks.

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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[]

Errori: 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).

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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[]

Errori: 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.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

204 Turned off

Errori: 400 · 401 · 403 · 404 · 429

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

List forwarding aliases

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domain`	string
`aliases`	ForwardAlias[]

Errori: 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.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all es. hello

curl

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

204 Deleted

Errori: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/targets` #

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

Ambiti: email:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`targets`	ForwardTarget[]

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

Errori: 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.

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. 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

Campo della risposta	Tipo	Descrizione
`domain`	string
`messages`	ForwardedMessage[]
`next_cursor`	string \| null

Errori: 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).

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`message_id` *	path	Message id (uuid) es. 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

Campo della risposta	Tipo	Descrizione
`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

Errori: 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.

Ambiti: email:read

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`domain`	string
`webhooks`	MailWebhook[]

Errori: 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.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

Errori: 400 · 401 · 403 · 404 · 429

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

Delete a mail webhook

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all es. hello

curl

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

204 Deleted

Errori: 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.

Ambiti: email:write · Idempotency-Key

Parametro	In	Descrizione
`domain` *	path	Domain name es. example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all es. 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

Campo della risposta	Tipo	Descrizione
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

Errori: 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.

Ambiti: webhooks:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`events`	object[]
`groups`	string[]

Errori: 400 · 401 · 403 · 404 · 429

GET `/webhooks` #

List webhook endpoints

Ambiti: webhooks:read

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`webhooks`	WebhookEndpoint[]

Errori: 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.

Ambiti: webhooks:write · Idempotency-Key

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

GET `/webhooks/{id}` #

Get a webhook endpoint. With its signing secret.

Ambiti: webhooks:read

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

PATCH `/webhooks/{id}` #

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

Ambiti: webhooks:write · Idempotency-Key

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42

Campo del body	Tipo	Descrizione
`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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

DELETE `/webhooks/{id}` #

Delete a webhook endpoint

Ambiti: webhooks:write · Idempotency-Key

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42

curl

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

204 Deleted

Errori: 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.

Ambiti: webhooks:write · Idempotency-Key

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42

curl

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

200 OK

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: webhooks:read

Parametro	In	Descrizione
`id` *	path	Numeric id es. 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

Campo della risposta	Tipo	Descrizione
`deliveries`	WebhookDelivery[]
`next_cursor`	string \| null

Errori: 400 · 401 · 403 · 404 · 429

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

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

Ambiti: webhooks:write · Idempotency-Key

Parametro	In	Descrizione
`id` *	path	Numeric id es. 42
`delivery_id` *	path	Delivery id (whd_...) es. 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

Campo della risposta	Tipo	Descrizione
`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

Errori: 400 · 401 · 403 · 404 · 429

Riferimento API REST

URL di base

Autenticazione

OpenAPI 3.1

Ambiti

Errori

Limiti di frequenza

Ritentare in sicurezza: 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` #