Source: skills/openmail/references/errors.md

OpenMail Error Reference

API error format

All errors return a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable description"
}

Error codes

Status	Code	Description	Resolution
400	`invalid_mailbox_name`	Mailbox name doesn’t meet format requirements	Use lowercase letters, numbers, and hyphens only (e.g. `my-agent`)
400	`missing_idempotency_key`	Send endpoint requires `Idempotency-Key` header	Add a UUID header; the CLI does this automatically
400	`bad_request` (invalid `replyTo`)	The `replyTo` field is not a valid email address	Pass a syntactically valid email or omit the field
401	`unauthorized`	Invalid or missing API key	Check `OPENMAIL_API_KEY` is set and starts with `om_`
403	`feature_requires_paid_plan` (`external_reply_to`)	Free plan tried to set `replyTo` to an address that isn’t one of their own OpenMail inboxes	Create the destination inbox and use its address, or upgrade to Pro or higher to use any external address
403	`forbidden`	The API key is scoped to one pod or one inbox, and this request touched something outside it — or an action its scope forbids, like creating or deleting an inbox	The `message` names the boundary that was crossed. Use the key belonging to that pod or inbox, or an account-wide key if the action needs one
404	`not_found`	Resource doesn’t exist or doesn’t belong to your account	Verify the inbox ID or thread ID is correct for this account
409	`address_taken`	Mailbox name or address already in use	Choose a different `--mailbox-name`
422	`recipient_suppressed`	Recipient is on the suppression list	The recipient previously unsubscribed or reported spam; do not contact them
422	`api_key_limit_reached`	The pod or inbox already has 20 active API keys	Revoke an unused key to free a slot
429	`rate_limit_exceeded`	Too many requests	Check `Retry-After` header and wait before retrying
429	`cold_outreach_limit`	Cold send limit exceeded for new inbox	New inboxes have a warm-up period; see email deliverability docs

CLI errors

`missing inbox id; run 'openmail init' or pass --inbox-id`

Setup hasn’t been run, or ~/.openclaw/openmail.env is missing. Run:

openmail setup --api-key "om_..."

`OpenMail API 401`

The API key is invalid or not being loaded. Verify:

grep OPENMAIL_API_KEY ~/.openclaw/openmail.env

The key should start with om_. Re-run setup if it is wrong or missing.

`cannot read attachment "..."`

The file path doesn’t exist or isn’t readable. Check the path is correct and the file exists before sending.

`missing --to`

The --to flag is required for openmail send. Always specify a recipient address.

`missing --subject`

The --subject flag is required when sending a new email (not a thread reply). Omit it only when using --thread-id.

Suppression

If you send to a suppressed address, the API returns 422 recipient_suppressed. Suppressed addresses cannot receive email from your account because they previously unsubscribed or reported spam. Do not attempt to work around this. To view or manage suppressions, go to Settings > Suppressions in the dashboard.

Attachment URLs

Attachment URLs in inbound messages are signed and expire after a short window. Fetch them promptly after receiving a message. If a URL has expired, re-fetch the message to get a fresh URL.

Rate limits

Resource	Limit
Inbox creation	100 per day per account
Send per inbox	10 per minute, 200 per day
API requests	1,000 per minute per account

When rate limited, wait for the duration specified in the Retry-After header before retrying.

Get started

Core concepts

WebSockets

Webhooks

Guides

Integrations

Best practices

Resources

Security & privacy

references/errors.md

OpenMail Error Reference

API error format

Error codes

CLI errors

`missing inbox id; run 'openmail init' or pass --inbox-id`

`OpenMail API 401`

`cannot read attachment "..."`

`missing --to`

`missing --subject`

Suppression

Attachment URLs

Rate limits

​OpenMail Error Reference

​API error format

​Error codes

​CLI errors

​missing inbox id; run 'openmail init' or pass --inbox-id

​OpenMail API 401

​cannot read attachment "..."

​missing --to

​missing --subject

​Suppression

​Attachment URLs

​Rate limits

OpenMail Error Reference

API error format

Error codes

CLI errors

`missing inbox id; run 'openmail init' or pass --inbox-id`

`OpenMail API 401`

`cannot read attachment "..."`

`missing --to`

`missing --subject`

Suppression

Attachment URLs

Rate limits