Email API

Before you start

Create an API key with email:read, and email:write to change things. Every endpoint is in the API reference and the OpenAPI file. Buying, upgrading and renewing a mail plan spends account credit and is done in the dashboard.

Mailboxes

A mail domain's plan has a storage size that its mailboxes share. Create a mailbox without a password and one is generated; the answer is the only time the API returns it.

$ 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", "quota_gb": 2}'

{"address": "info@example.com", "username": "info", "full_name": "Info", "quota_gb": 2,
 "used_gb": "0.00", "aliases": [], "password": "Qm7…"}

Free forwarding

Domains registered at NameOcean that use our nameservers can forward their mail for free. Turning it on writes the MX record; if the zone has another provider's MX records, send replace_mx: true to remove them.

$ curl -X POST https://nameocean.net/api/v1/email/forwarding/example.com \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY"
$ 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"}'

A new target address gets a mail with a link and a 6-digit code, and mail is forwarded once its owner confirms (the link, or POST /email/forwarding/targets/{id}/verify with the code). * forwards every address without its own alias. GET /email/forwarding/{domain}/messages lists the last 30 days of mail with its status; held mail (spam, over the daily limit) can be forwarded with /release.

Incoming mail to webhook

Instead of forwarding, an address can post each mail it receives to your HTTPS endpoint as JSON: bodies, headers and attachments in base64. It is open after a short review of what you will use it for; ask on a domain's Email Forwarding page.

$ 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"}'

X-NameOcean-Event: email.received
X-NameOcean-Signature: t=1794300000,v1=5f2b…

{
  "id": "6f1c2a4e-8b3d-4f5a-9c7e-1d2b3a4c5e6f",
  "event": "email.received",
  "envelope": {"from": "alice@example.org", "to": "inbound@example.com"},
  "from": "Alice <alice@example.org>",
  "subject": "Order 1042",
  "text": "Hi…",
  "html": "<p>Hi…</p>",
  "headers": [["From", "Alice <alice@example.org>"], …],
  "attachments": [{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 48211,
                   "content_base64": "JVBERi0…"}],
  "spam_score": 0.4,
  "size": 66120
}

The signature works like the account webhooks: see verifying a signature.

Events

Account webhooks can subscribe to email.*: email.mailbox.created, email.mailbox.deleted, email.forwarding.enabled and email.forwarding.disabled (also sent when a domain stops qualifying for free forwarding, with the reason).

From the terminal

$ nameocean email mailboxes add example.com info --name "Info"
$ nameocean email aliases add example.com sales info
$ nameocean email check example.com
$ nameocean email forwards on example.com
$ nameocean email forwards add example.com hello me@gmail.com
$ nameocean email inbound add example.com support https://example.com/hooks/mail

Every command takes --json. Install and all commands: CLI.

From your AI

Over MCP an assistant can list your mail domains, check their DNS, create mailboxes and aliases, and turn forwarding on. Mailbox passwords are never sent to the AI: you read them in the dashboard.