Mail that fits your workflow.

Start with two kinds of credentials

All endpoints use /api/v1/index.php?action=ACTION. Successful responses have {"ok":true,"data":{...}}. Keep HTTPS enabled.

Create a named inbox

Create a random 64-character hexadecimal request key and save it before sending. Reuse the same key and address if the response is interrupted. The normal domain, lifetime and access-password rules still apply.

curl 'https://omailo.net/api/v1/index.php?action=create_inbox' \
  -H "X-Omailo-Api-Key: $OMAILO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"alias":"your-unique-name","domain":"omailo.net", "lifetime_seconds":3600,"request_key":"YOUR_SAVED_64_HEX_REQUEST_KEY"}'

Save data.inbox.id and data.inbox.token. For random or bulk creation, call bulk_preview first, save the preview and request key, then submit the available rows to bulk_create in groups of 20. A preview checks availability without reserving addresses. Generated proofs expire after 30 minutes. Named single creation remains available when bulk creation is disabled; both still follow registration and access-plan rules.

Generate addresses your way

Pass generation to bulk_preview with mode: "generate". Omit it to use the natural mix of one or two names, punctuation and zero to three digits. Generate 1–500 addresses, select permitted domains and set lifetime_seconds before creating them.

{
  "mode": "generate",
  "count": 100,
  "domains": ["omailo.net"],
  "lifetime_seconds": 86400,
  "generation": {
    "name_pool": "all",
    "styles": ["first_last", "initial_last"],
    "separators": ["."],
    "digit_lengths": [0],
    "max_length": 24,
    "domain_distribution": "balanced"
  }
}

Names and affixes are trimmed and lowercased. A selected separator joins the name components and any affixes; digits attach directly at the start or end. Generation uses combinations that fit the length limit without cutting names. Impossible settings return generation_impossible; unsupported options return invalid_generation_options.

The response includes normalized generation and name_pool_stats. Inspect row statuses if your choices provide fewer unique available addresses than requested. Save the returned rows and submit them unchanged to bulk_create. Website style examples do not check availability; the server preview does.

Change remaining time and web sending

GET inbox_controls with inboxes:read permission and the inbox's private credentials. The response includes its current metadata, a revision, permitted expiry.allowed_lifetimes and current sending capabilities. POST requires the new inboxes:write scope.

{
  "revision": "LATEST_REVISION_FROM_GET_INBOX_CONTROLS",
  "lifetime_seconds": 86400,
  "web_sending_enabled": true
}

Supply either change or both. A chosen lifetime starts when the server saves it; the original access plan and administrator limits apply. Zero requests unlimited only when currently offered. The server authenticates the private key again before updating. Expired or deleted inboxes cannot be restored. A 409 means the inbox changed: reload, review the new values and decide whether to submit again.

If an update response is interrupted, GET the current settings before retrying. Blindly resubmitting a duration could restart its countdown. Successful responses include fresh metadata, a new revision, changed and cancelled_outgoing.

web_sending_enabled opts the inbox into browser sending where an administrator has enabled a verified SMTP sender. Turning it off cancels pending browser-owner submissions. Developer API sending continues to require its separate messages:send scope and remains independent of this checkbox. SMTP credentials stay on the server.

Receive and organize mail

List and detail requests leave read status unchanged. Search with q or from, filter with read=unread, and follow pagination.next_cursor for older messages.

curl 'https://omailo.net/api/v1/index.php?action=messages&read=unread&limit=50' \
  -H "X-Omailo-Api-Key: $OMAILO_API_KEY" \
  -H "X-Inbox-Id: $INBOX_ID" \
  -H "X-Inbox-Token: $INBOX_TOKEN"

Inbox addresses and expiry can be changed by an administrator. Refresh returned inbox metadata instead of assuming the original lifetime; a rotated private token requires the new link. GET reads stored mail. To request a source-mailbox refresh, POST to messages or verification_code with {"fetch":true}. Fetching respects the receiver throttle and shared worker lock. Normal cron keeps importing mail even when no page is open.

Poll every 5–10 seconds and honor Retry-After. Verification-code extraction is a best-effort convenience; check the returned message context and confidence before using a match.

Queue outgoing mail

API sending becomes available after an administrator configures and tests SMTP, enables the outbox, and issues a key with messages:send. Each domain can have its own SMTP connection; untouched automatic profiles retain the existing global sender. Sending uses the configured mailbox as From and your temporary inbox as Reply-To.

curl 'https://omailo.net/api/v1/index.php?action=send' \
  -H "X-Omailo-Api-Key: $OMAILO_API_KEY" \
  -H "X-Inbox-Id: $INBOX_ID" \
  -H "X-Inbox-Token: $INBOX_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"to":"recipient@example.com","subject":"Hello","text":"Your message", "request_key":"YOUR_SAVED_64_HEX_REQUEST_KEY"}'

This queues one message for cron. Plain text remains supported; optional HTML and attachments add formatted messages and embedded images. Keep the returned outgoing ID, and call outbox to track it. Request keys prevent accidental duplicate submissions; changing the message requires a new key.

For formatted mail, include html (up to 200,000 UTF-8 bytes) and a required text alternative (up to 50,000 bytes). Include up to five attachments with filename, content_type, content_base64 and disposition. The combined decoded limit is 5 MiB; send requests accept up to 8 MiB JSON. Inline PNG, JPEG, GIF and WebP images use disposition: "inline", a unique content_id such as logo@omailo, and <img src="cid:logo@omailo"> in HTML. The server sanitizes HTML and checks files.

The original access password must permit SMTP sending. A developer key cannot bypass a denied or expired password rule. Read the inbox controls to inspect available sending features. After a connection failure, retry with the same request key and the same complete payload, including HTML and file bytes.

Only failures known to occur before acceptance are eligible for automatic retry. Messages in an uncertain state are not automatically resent. Queued mail can be cancelled before the worker claims it.

API reference

Download the OpenAPI specification for detailed inputs and response schemas.

Predictable errors and retries

Errors include error.code and a readable error.message. Keep the X-Request-Id header when reporting a failed request; omit private credentials from reports.