Agent documentation

Use OceanInbox in automated signup tests.

Create an account, generate an API key, create an `@oceaninbox.com` mailbox, then read verification emails through the API.

1. Create an account

Register at /auth?mode=register, then open the dashboard and create an API key. Store the full `oi_live_...` key immediately because it is only shown once.

2. Create a mailbox

Agents use the account API key as `x-api-key`. The returned address is the email address to enter into the service being tested.

3. Read the OTP

Poll `/otp` for numeric codes or `/messages` when the service sends a magic link. Use a short delay between polling attempts.

Authentication

All mailbox API calls use `https://api.oceaninbox.com` and require an account-scoped API key in the `x-api-key` header.

export OCEANINBOX_API_KEY='oi_live_replace_me'

Create a mailbox

Create the mailbox before registering at the target service. Use the returned address exactly as the email address in that signup form. Do not use an @scalemule.com address for OceanInbox tests.

curl -sS -X POST https://api.oceaninbox.com/v1/mailboxes \
  -H "content-type: application/json" \
  -H "x-api-key: $OCEANINBOX_API_KEY" \
  -d '{
    "ttlSeconds": 3600,
    "metadata": {
      "flow": "signup",
      "target": "example-service"
    }
  }'

If the agent needs a predictable mailbox handle, send localPart. OceanInbox appends @oceaninbox.com for you.

curl -sS -X POST https://api.oceaninbox.com/v1/mailboxes \
  -H "content-type: application/json" \
  -H "x-api-key: $OCEANINBOX_API_KEY" \
  -d '{
    "localPart": "coralmeet-e2e-20260705-001",
    "ttlSeconds": 7200,
    "metadata": {
      "flow": "signup",
      "target": "coralmeet",
      "runId": "20260705-001"
    }
  }'
localPartOptional mailbox handle before @oceaninbox.com. If omitted, OceanInbox generates a unique kf-... handle. Allowed: lowercase letters, numbers, dot, underscore, and hyphen. Must start and end with a lowercase letter or number. If the handle already exists, the API returns 409.
ttlSecondsOptional retention time in seconds. Minimum 60. Maximum 2592000 (30 days). Use 3600 for 1 hour, 7200 for 2 hours, or 86400 for 1 day. If omitted, expiresAt is null.
metadataOptional string-to-string labels for tracing automation runs. Use values such as flow, target, and runId. Metadata is returned when listing mailboxes.
{
  "address": "kf-n7sq4r8m2p1d@oceaninbox.com",
  "createdAt": "2026-07-05T04:30:00.000Z",
  "expiresAt": "2026-07-05T05:30:00.000Z",
  "ownerId": "019f...",
  "metadata": {
    "flow": "signup",
    "target": "example-service"
  }
}

Save the returned address into ADDRESS before polling for messages:

mailbox_json=$(curl -sS -X POST https://api.oceaninbox.com/v1/mailboxes \
  -H "content-type: application/json" \
  -H "x-api-key: $OCEANINBOX_API_KEY" \
  -d '{"ttlSeconds":3600,"metadata":{"flow":"signup","target":"example-service"}}')

export ADDRESS=$(printf '%s' "$mailbox_json" | node -pe 'JSON.parse(require("node:fs").readFileSync(0, "utf8")).address')
echo "Use this email in the target service signup form: $ADDRESS"

Read messages

The messages endpoint returns sender, subject, date, plain text, and HTML for recent messages. Use `search` to filter by sender, subject, text, or HTML. Use `sort=desc` to return the latest email first, or `sort=asc` to read oldest first.

curl -sS "https://api.oceaninbox.com/v1/mailboxes/$ADDRESS/messages?limit=10&search=verification&sort=desc" \
  -H "x-api-key: $OCEANINBOX_API_KEY"

Extract an OTP

The OTP endpoint checks recent messages in the requested sort order. Use `sort=desc` when the agent needs the latest code. By default it matches numeric codes from 4 to 8 digits.

curl -sS "https://api.oceaninbox.com/v1/mailboxes/$ADDRESS/otp?limit=10&sort=desc" \
  -H "x-api-key: $OCEANINBOX_API_KEY"
{
  "otp": "123456",
  "checkedMessages": 1
}

Polling pattern

Poll every few seconds after submitting the target service signup form. Avoid tight retry loops.

for attempt in $(seq 1 30); do
  otp_json=$(curl -sS "https://api.oceaninbox.com/v1/mailboxes/$ADDRESS/otp?limit=10&sort=desc" \
    -H "x-api-key: $OCEANINBOX_API_KEY")
  otp=$(printf '%s' "$otp_json" | node -pe 'JSON.parse(require("node:fs").readFileSync(0, "utf8")).otp || ""')
  if [ -n "$otp" ]; then
    echo "$otp"
    exit 0
  fi
  sleep 2
done

echo "OTP not found" >&2
exit 1

Status codes

200Request succeeded.
201Mailbox or API key created.
204Mailbox deleted.
401Missing or invalid API key.
404Mailbox not found or not owned by this account.
409Mailbox local part already exists.
429Rate limit exceeded.

Agent rules