Entwickler → REST API

REST-API-Referenz

Domains, DNS, SSL und App-Server über HTTPS. JSON rein, JSON raus, eine Basis-URL.

Basis-URL

https://nameocean.net/api/v1

Authentifizierung

Authorization: Bearer <key> mit einem Schlüssel aus Dashboard → API-Schlüssel.

OpenAPI 3.1

/api/v1/openapi.json · in Postman, Insomnia oder Bruno importieren oder einen Client generieren.

Scopes

Jeder Schlüssel hat Berechtigungen. GET benötigt <area>:read, andere Methoden <area>:write; bei jedem Endpunkt unten steht, was er braucht. Fehlt die Berechtigung, lautet die Antwort 403 mit dem Code missing_scope und required_scopes. Alle Scopes.

Fehler

Jeder Fehler hat dieselbe Struktur: eine Meldung für Menschen und KI-Agenten sowie einen stabilen Code für Verzweigungen. field nennt die fehlerhafte Eingabe, sofern es eine gibt.

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

Rate Limits

120 Anfragen pro Minute und Konto. Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Sekunden, bis wieder ein Platz frei wird). Bei Überschreitung lautet die Antwort 429 mit dem Code rate_limited und retry_after in Sekunden.

Sicher wiederholen: Idempotency-Key

Senden Sie bei POST, PUT, PATCH und DELETE einen Idempotency-Key-Header (eine UUID) mit. Bricht die Verbindung ab, wiederholen Sie die Anfrage mit demselben Schlüssel: Sie erhalten die erste Antwort mit Idempotent-Replayed: true zurück, und die Domain wird weder doppelt registriert noch doppelt berechnet. Erfolgreiche Antworten werden pro Konto 24 Stunden lang gespeichert; derselbe Schlüssel mit einer anderen Anfrage wird mit 422 idempotency_key_reused abgelehnt. Fehler werden nicht gespeichert. Nachdem Sie die Ursache behoben haben (zum Beispiel durch Aufladen Ihres Guthabens), wird eine Wiederholung mit demselben Schlüssel also erneut ausgeführt.

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.

Scopes: keine

curl

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

200 OK

Fehler: 400 · 401 · 404 · 429

GET `/account` #

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

Scopes: account:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`email`	string
`credit`	string	USD amount as a decimal string
`currency`	"USD"
`domains`	integer
`dns_zones`	integer
`add_funds_url`	string

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

Scopes: account:read

Parameter	In	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`events`	AuditEvent[]
`next_cursor`	string \| null

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

Scopes: domains:read

Parameter	In	Beschreibung
`name` *	query	z. B. 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

Antwortfeld	Typ	Beschreibung
`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"

Fehler: 400 · 401 · 403 · 404 · 429

GET `/domains` #

List domains

Scopes: domains:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domains`	Domain[]

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

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

Body-Feld	Typ	Beschreibung
`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.

Antwortfeld	Typ	Beschreibung
`name`	string
`records`	Record[]
`hint`	string

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

GET `/domains/{name}` #

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

Scopes: domains:read

Parameter	In	Beschreibung
`name` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

PATCH `/domains/{name}` #

Change auto-renew or lock

Scopes: domains:write · Idempotency-Key

Parameter	In	Beschreibung
`name` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: domains:write · Idempotency-Key

Parameter	In	Beschreibung
`name` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

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

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

Parameter	In	Beschreibung
`name` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`renewed`	string
`charged`	string	USD amount as a decimal string
`credit`	string	USD amount as a decimal string

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

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

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

Scopes: domains:write

Parameter	In	Beschreibung
`name` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`name`	string
`auth_code`	string

Fehler: 400 · 401 · 403 · 404 · 429

DNS

Zones and records.

GET `/dns` #

List DNS zones

Scopes: dns:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`zones`	object[]

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

Scopes: dns:write · Idempotency-Key

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`name`	string
`records`	Record[]
`hint`	string

Fehler: 400 · 401 · 403 · 404 · 429

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

List records

Scopes: dns:read

Parameter	In	Beschreibung
`zone` *	path	DNS zone (domain) name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`zone`	string
`records`	Record[]

Fehler: 400 · 401 · 403 · 404 · 429

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

Add a record

Scopes: dns:write · Idempotency-Key

Parameter	In	Beschreibung
`zone` *	path	DNS zone (domain) name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

Get a record

Scopes: dns:read

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

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

Change a record. Send only the fields to change.

Scopes: dns:write · Idempotency-Key

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

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

Replace a record. Same as PATCH.

Scopes: dns:write · Idempotency-Key

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

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

Delete a record

Scopes: dns:write · Idempotency-Key

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

curl

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

204 Deleted

Fehler: 400 · 401 · 403 · 404 · 429

SSL

Free wildcard certificates.

GET `/ssl/{zone}` #

Certificate status

Scopes: ssl:read

Parameter	In	Beschreibung
`zone` *	path	DNS zone (domain) name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

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

Scopes: ssl:write · Idempotency-Key

Parameter	In	Beschreibung
`zone` *	path	DNS zone (domain) name z. B. example.com

curl

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

202 Issuing

Antwortfeld	Typ	Beschreibung
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Fehler: 400 · 401 · 403 · 404 · 429

PATCH `/ssl/{zone}` #

Change auto-renew

Scopes: ssl:write · Idempotency-Key

Parameter	In	Beschreibung
`zone` *	path	DNS zone (domain) name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`zone`	string
`status`	string	One of: none, issuing, waiting_for_nameservers, active
`auto_renew`	boolean
`expires_on`	string \| null
`download_url`	string \| null

Fehler: 400 · 401 · 403 · 404 · 429

Servers

App servers: ports and domain bindings.

GET `/servers` #

List app servers

Scopes: servers:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`servers`	Server[]

Fehler: 400 · 401 · 403 · 404 · 429

GET `/servers/{server}` #

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

Scopes: servers:read

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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[]

Fehler: 400 · 401 · 403 · 404 · 429

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

List open ports

Scopes: servers:read

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`server`	string
`ports`	Port[]

Fehler: 400 · 401 · 403 · 404 · 429

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

Open a port. The external port is assigned.

Scopes: servers:write · Idempotency-Key

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`id`	integer
`protocol`	string	One of: tcp, udp
`internal_port`	integer
`external_port`	integer
`connect_to`	string	Only when the port was just opened.

Fehler: 400 · 401 · 403 · 404 · 429

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

Close a port

Scopes: servers:write · Idempotency-Key

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e
`id` *	path	Numeric id z. B. 42

curl

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

204 Closed

Fehler: 400 · 401 · 403 · 404 · 429

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

List bound domains

Scopes: servers:read

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`server`	string
`domains`	Binding[]

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

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

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`id`	integer
`domain`	string
`status`	string	One of: setting_up, active
`url`	string

Fehler: 400 · 401 · 403 · 404 · 429

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

Unbind a domain

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

Parameter	In	Beschreibung
`server` *	path	Server id, or its default domain such as 3f9a1c2e.nameocean.org z. B. 3f9a1c2e
`id` *	path	Numeric id z. B. 42

curl

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

204 Unbound

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

Scopes: email:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domains`	MailDomain[]

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

Change mail auto-renew

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

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

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. 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

Antwortfeld	Typ	Beschreibung
`domain`	string
`ok`	boolean
`checks`	object	ns, mx, spf, dkim, dmarc

Fehler: 400 · 401 · 403 · 404 · 429

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

List mailboxes

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domain`	string
`mailboxes`	Mailbox[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Fehler: 400 · 401 · 403 · 404 · 429

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

Get a mailbox

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) z. B. info

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Fehler: 400 · 401 · 403 · 404 · 429

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

Change a mailbox. Send only what changes.

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) z. B. info

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) z. B. info

curl

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

204 Deleted

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`username` *	path	Mailbox name, the part before @ (or the full address) z. B. info

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`address`	string
`username`	string
`full_name`	string
`quota_gb`	integer
`used_gb`	string
`aliases`	string[]
`password`	string	Only in the answer that set it

Fehler: 400 · 401 · 403 · 404 · 429

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

List mail aliases

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domain`	string
`aliases`	MailAlias[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`address`	string
`mailbox`	string	The mailbox that receives it

Fehler: 400 · 401 · 403 · 404 · 429

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

Delete a mail alias

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`alias` *	path	Alias address, or the part before @ z. B. sales

curl

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

204 Deleted

Fehler: 400 · 401 · 403 · 404 · 429

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

List mailing lists

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domain`	string
`lists`	MailingList[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`address`	string
`name`	string
`members`	string[]

Fehler: 400 · 401 · 403 · 404 · 429

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

Get a mailing list

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`address` *	path	Mailing list address, or the part before @ z. B. team

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`address`	string
`name`	string
`members`	string[]

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`address` *	path	Mailing list address, or the part before @ z. B. team

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`address`	string
`name`	string
`members`	string[]

Fehler: 400 · 401 · 403 · 404 · 429

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

Delete a mailing list

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`address` *	path	Mailing list address, or the part before @ z. B. team

curl

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

204 Deleted

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

Scopes: email:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domains`	Forwarding[]

Fehler: 400 · 401 · 403 · 404 · 429

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

Get forwarding. Aliases and mail webhooks.

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

204 Turned off

Fehler: 400 · 401 · 403 · 404 · 429

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

List forwarding aliases

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domain`	string
`aliases`	ForwardAlias[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: email:write · Idempotency-Key

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

curl

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

204 Deleted

Fehler: 400 · 401 · 403 · 404 · 429

GET `/email/forwarding/targets` #

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

Scopes: email:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`targets`	ForwardTarget[]

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`id`	integer
`email`	string
`status`	string	One of: pending, confirmed, refused
`confirmed_at`	string \| null

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

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. 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

Antwortfeld	Typ	Beschreibung
`domain`	string
`messages`	ForwardedMessage[]
`next_cursor`	string \| null

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com
`message_id` *	path	Message id (uuid) z. B. 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

Antwortfeld	Typ	Beschreibung
`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

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

Scopes: email:read

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`domain`	string
`webhooks`	MailWebhook[]

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

Scopes: email:write · Idempotency-Key

Parameter	In	Beschreibung
`domain` *	path	Domain name z. B. example.com

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

Fehler: 400 · 401 · 403 · 404 · 429

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

Delete a mail webhook

Scopes: email:write · Idempotency-Key

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

curl

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

204 Deleted

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

Scopes: email:write · Idempotency-Key

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

Antwortfeld	Typ	Beschreibung
`localpart`	string
`address`	string
`catch_all`	boolean
`url`	string
`active`	boolean
`created_at`	string \| null
`secret`	string	whsec_...; signs X-NameOcean-Signature

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

Scopes: webhooks:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`events`	object[]
`groups`	string[]

Fehler: 400 · 401 · 403 · 404 · 429

GET `/webhooks` #

List webhook endpoints

Scopes: webhooks:read

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`webhooks`	WebhookEndpoint[]

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

Scopes: webhooks:write · Idempotency-Key

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

GET `/webhooks/{id}` #

Get a webhook endpoint. With its signing secret.

Scopes: webhooks:read

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

PATCH `/webhooks/{id}` #

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

Scopes: webhooks:write · Idempotency-Key

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42

Body-Feld	Typ	Beschreibung
`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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

DELETE `/webhooks/{id}` #

Delete a webhook endpoint

Scopes: webhooks:write · Idempotency-Key

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42

curl

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

204 Deleted

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

Scopes: webhooks:write · Idempotency-Key

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42

curl

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

200 OK

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: webhooks:read

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 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

Antwortfeld	Typ	Beschreibung
`deliveries`	WebhookDelivery[]
`next_cursor`	string \| null

Fehler: 400 · 401 · 403 · 404 · 429

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

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

Scopes: webhooks:write · Idempotency-Key

Parameter	In	Beschreibung
`id` *	path	Numeric id z. B. 42
`delivery_id` *	path	Delivery id (whd_...) z. B. 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

Antwortfeld	Typ	Beschreibung
`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

Fehler: 400 · 401 · 403 · 404 · 429

REST-API-Referenz

Basis-URL

Authentifizierung

OpenAPI 3.1

Scopes

Fehler

Rate Limits

Sicher wiederholen: 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` #