Développeurs → REST API

Référence de l'API REST

Domaines, DNS, SSL et serveurs d'applications via HTTPS. Du JSON en entrée, du JSON en sortie, une seule URL de base.

URL de base

https://nameocean.net/api/v1

Authentification

Authorization: Bearer <key> avec une clé issue de Tableau de bord → Clés API.

OpenAPI 3.1

/api/v1/openapi.json · importez-le dans Postman, Insomnia ou Bruno, ou générez un client.

Permissions

Chaque clé dispose de permissions. GET requiert <area>:read, les autres méthodes <area>:write ; chaque endpoint ci-dessous indique ce dont il a besoin. Sans cela, la réponse est une erreur 403 avec le code missing_scope et required_scopes. Toutes les permissions.

Erreurs

Toutes les erreurs ont la même structure : un message rédigé pour les humains et les agents IA, et un code stable sur lequel baser votre logique. field indique le champ en cause, le cas échéant.

HTTP 400

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

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

Limites de débit

120 requêtes par minute et par compte. Chaque réponse inclut X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes avant qu'un créneau se libère). Au-delà de la limite, la réponse est une erreur 429 avec le code rate_limited et retry_after en secondes.

Réessayer en toute sécurité : Idempotency-Key

Envoyez un en-tête Idempotency-Key (un UUID) avec les requêtes POST, PUT, PATCH et DELETE. Si la connexion est interrompue, relancez la requête avec la même clé : vous recevez la première réponse accompagnée de Idempotent-Replayed: true, et le domaine n'est ni enregistré ni facturé deux fois. Les réponses réussies sont conservées pendant 24 heures par compte ; la même clé utilisée avec une requête différente est refusée avec 422 idempotency_key_reused. Les erreurs ne sont pas conservées : après avoir corrigé leur cause (en ajoutant du crédit, par exemple), une nouvelle tentative avec la même clé est exécutée à nouveau.

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.

Permissions: aucune

curl

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

200 OK

Erreurs: 400 · 401 · 404 · 429

GET `/account` #

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

Permissions: account:read

curl

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

200 OK

Champ de réponse	Type	Description
`email`	string
`credit`	string	USD amount as a decimal string
`currency`	"USD"
`domains`	integer
`dns_zones`	integer
`add_funds_url`	string

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

Permissions: account:read

Paramètre	Emplacement	Description
`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

Champ de réponse	Type	Description
`events`	AuditEvent[]
`next_cursor`	string \| null

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

Permissions: domains:read

Paramètre	Emplacement	Description
`name` *	query	ex. 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

Champ de réponse	Type	Description
`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"

Erreurs: 400 · 401 · 403 · 404 · 429

GET `/domains` #

List domains

Permissions: domains:read

curl

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

200 OK

Champ de réponse	Type	Description
`domains`	Domain[]

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

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

Champ du corps	Type	Description
`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.

Champ de réponse	Type	Description
`name`	string
`records`	Record[]
`hint`	string

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

GET `/domains/{name}` #

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

Permissions: domains:read

Paramètre	Emplacement	Description
`name` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

PATCH `/domains/{name}` #

Change auto-renew or lock

Permissions: domains:write · Idempotency-Key

Paramètre	Emplacement	Description
`name` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: domains:write · Idempotency-Key

Paramètre	Emplacement	Description
`name` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

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

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

Paramètre	Emplacement	Description
`name` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`renewed`	string
`charged`	string	USD amount as a decimal string
`credit`	string	USD amount as a decimal string

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

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

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

Permissions: domains:write

Paramètre	Emplacement	Description
`name` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`name`	string
`auth_code`	string

Erreurs: 400 · 401 · 403 · 404 · 429

DNS

Zones and records.

GET `/dns` #

List DNS zones

Permissions: dns:read

curl

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

200 OK

Champ de réponse	Type	Description
`zones`	object[]

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

Permissions: dns:write · Idempotency-Key

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`name`	string
`records`	Record[]
`hint`	string

Erreurs: 400 · 401 · 403 · 404 · 429

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

List records

Permissions: dns:read

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`zone`	string
`records`	Record[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

Add a record

Permissions: dns:write · Idempotency-Key

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

Get a record

Permissions: dns:read

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT ex. A
`id` *	path	Numeric id ex. 42

curl

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

200 OK

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

Change a record. Send only the fields to change.

Permissions: dns:write · Idempotency-Key

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT ex. A
`id` *	path	Numeric id ex. 42

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

Replace a record. Same as PATCH.

Permissions: dns:write · Idempotency-Key

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT ex. A
`id` *	path	Numeric id ex. 42

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

Delete a record

Permissions: dns:write · Idempotency-Key

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com
`type` *	path	Record type: A, CNAME, MX, TXT, SRV, PTR or REDIRECT ex. A
`id` *	path	Numeric id ex. 42

curl

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

204 Deleted

Erreurs: 400 · 401 · 403 · 404 · 429

SSL

Free wildcard certificates.

GET `/ssl/{zone}` #

Certificate status

Permissions: ssl:read

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

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

Permissions: ssl:write · Idempotency-Key

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com

curl

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

202 Issuing

Champ de réponse	Type	Description
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Erreurs: 400 · 401 · 403 · 404 · 429

PATCH `/ssl/{zone}` #

Change auto-renew

Permissions: ssl:write · Idempotency-Key

Paramètre	Emplacement	Description
`zone` *	path	DNS zone (domain) name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Erreurs: 400 · 401 · 403 · 404 · 429

Servers

App servers: ports and domain bindings.

GET `/servers` #

List app servers

Permissions: servers:read

curl

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

200 OK

Champ de réponse	Type	Description
`servers`	Server[]

Erreurs: 400 · 401 · 403 · 404 · 429

GET `/servers/{server}` #

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

Permissions: servers:read

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e

curl

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

200 OK

Champ de réponse	Type	Description
`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[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

List open ports

Permissions: servers:read

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e

curl

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

200 OK

Champ de réponse	Type	Description
`server`	string
`ports`	Port[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

Open a port. The external port is assigned.

Permissions: servers:write · Idempotency-Key

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`id`	integer
`protocol`	string	One of: tcp, udp
`internal_port`	integer
`external_port`	integer
`connect_to`	string	Only when the port was just opened.

Erreurs: 400 · 401 · 403 · 404 · 429

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

Close a port

Permissions: servers:write · Idempotency-Key

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e
`id` *	path	Numeric id ex. 42

curl

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

204 Closed

Erreurs: 400 · 401 · 403 · 404 · 429

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

List bound domains

Permissions: servers:read

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e

curl

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

200 OK

Champ de réponse	Type	Description
`server`	string
`domains`	Binding[]

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

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

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`id`	integer
`domain`	string
`status`	string	One of: setting_up, active
`url`	string

Erreurs: 400 · 401 · 403 · 404 · 429

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

Unbind a domain

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

Paramètre	Emplacement	Description
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org ex. 3f9a1c2e
`id` *	path	Numeric id ex. 42

curl

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

204 Unbound

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

Permissions: email:read

curl

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

200 OK

Champ de réponse	Type	Description
`domains`	MailDomain[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

Change mail auto-renew

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

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

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. 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

Champ de réponse	Type	Description
`domain`	string
`ok`	boolean
`checks`	object	ns, mx, spf, dkim, dmarc

Erreurs: 400 · 401 · 403 · 404 · 429

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

List mailboxes

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`domain`	string
`mailboxes`	Mailbox[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Erreurs: 400 · 401 · 403 · 404 · 429

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

Get a mailbox

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) ex. info

curl

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

200 OK

Champ de réponse	Type	Description
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Erreurs: 400 · 401 · 403 · 404 · 429

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

Change a mailbox. Send only what changes.

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) ex. info

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) ex. info

curl

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

204 Deleted

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) ex. info

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Erreurs: 400 · 401 · 403 · 404 · 429

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

List mail aliases

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`domain`	string
`aliases`	MailAlias[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`address`	string
`mailbox`	string	The mailbox that receives it

Erreurs: 400 · 401 · 403 · 404 · 429

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

Delete a mail alias

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`alias` *	path	Alias address, or the part before @ ex. sales

curl

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

204 Deleted

Erreurs: 400 · 401 · 403 · 404 · 429

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

List mailing lists

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`domain`	string
`lists`	MailingList[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`address`	string
`name`	string
`members`	string[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

Get a mailing list

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`address` *	path	Mailing list address, or the part before @ ex. team

curl

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

200 OK

Champ de réponse	Type	Description
`address`	string
`name`	string
`members`	string[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`address` *	path	Mailing list address, or the part before @ ex. team

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`address`	string
`name`	string
`members`	string[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

Delete a mailing list

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`address` *	path	Mailing list address, or the part before @ ex. team

curl

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

204 Deleted

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

Permissions: email:read

curl

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

200 OK

Champ de réponse	Type	Description
`domains`	Forwarding[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

Get forwarding. Aliases and mail webhooks.

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`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[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

204 Turned off

Erreurs: 400 · 401 · 403 · 404 · 429

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

List forwarding aliases

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`domain`	string
`aliases`	ForwardAlias[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all ex. hello

curl

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

204 Deleted

Erreurs: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/targets` #

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

Permissions: email:read

curl

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

200 OK

Champ de réponse	Type	Description
`targets`	ForwardTarget[]

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42

curl

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

200 OK

Champ de réponse	Type	Description
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

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

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. 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

Champ de réponse	Type	Description
`domain`	string
`messages`	ForwardedMessage[]
`next_cursor`	string \| null

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`message_id` *	path	Message id (uuid) ex. 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

Champ de réponse	Type	Description
`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

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

Permissions: email:read

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

curl

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

200 OK

Champ de réponse	Type	Description
`domain`	string
`webhooks`	MailWebhook[]

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

Erreurs: 400 · 401 · 403 · 404 · 429

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

Delete a mail webhook

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all ex. hello

curl

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

204 Deleted

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

Permissions: email:write · Idempotency-Key

Paramètre	Emplacement	Description
`domain` *	path	Domain name ex. example.com
`localpart` *	path	The part before @, or * (%2A) for the catch-all ex. 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

Champ de réponse	Type	Description
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

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

Permissions: webhooks:read

curl

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

200 OK

Champ de réponse	Type	Description
`events`	object[]
`groups`	string[]

Erreurs: 400 · 401 · 403 · 404 · 429

GET `/webhooks` #

List webhook endpoints

Permissions: webhooks:read

curl

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

200 OK

Champ de réponse	Type	Description
`webhooks`	WebhookEndpoint[]

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

Permissions: webhooks:write · Idempotency-Key

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

GET `/webhooks/{id}` #

Get a webhook endpoint. With its signing secret.

Permissions: webhooks:read

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42

curl

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

200 OK

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

PATCH `/webhooks/{id}` #

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

Permissions: webhooks:write · Idempotency-Key

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42

Champ du corps	Type	Description
`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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

DELETE `/webhooks/{id}` #

Delete a webhook endpoint

Permissions: webhooks:write · Idempotency-Key

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42

curl

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

204 Deleted

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

Permissions: webhooks:write · Idempotency-Key

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42

curl

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

200 OK

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: webhooks:read

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 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

Champ de réponse	Type	Description
`deliveries`	WebhookDelivery[]
`next_cursor`	string \| null

Erreurs: 400 · 401 · 403 · 404 · 429

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

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

Permissions: webhooks:write · Idempotency-Key

Paramètre	Emplacement	Description
`id` *	path	Numeric id ex. 42
`delivery_id` *	path	Delivery id (whd_...) ex. 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

Champ de réponse	Type	Description
`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

Erreurs: 400 · 401 · 403 · 404 · 429

Référence de l'API REST

URL de base

Authentification

OpenAPI 3.1

Permissions

Erreurs

Limites de débit

Réessayer en toute sécurité : 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` #