Inboxes

Create an inbox

Creates an address that receives mail. Omit domain for an inbox on the shared domain — ready immediately, no DNS. To use your own domain, it must be verified in this project and its MX record must already point at inbound-smtp.<region>.amazonaws.com; use a dedicated subdomain (e.g. agents.yourcompany.com), never the domain your team's mail lives on — a domain whose MX points elsewhere is refused with domain_receives_elsewhere.

Pass clientId to make creation idempotent: a repeat returns the existing inbox with 200. Addresses are never recycled — a deleted inbox's address can't be created again by anyone.

post/v1/inboxes

Request

  • Base URL: https://api.volanea.com
  • URL: https://api.volanea.com/v1/inboxes
  • Auth: HTTP bearer

Request body

usernamestring

Local part. Random (inbox-…) if omitted.

domainstring

A verified domain of yours. Omit for the shared domain.

displayNamestring nullable
clientIdstring
metadataobject
securityMode'off' | 'tag' | 'hold'

Response

An inbox with this clientId already existed.

inboxIdstring required
addressstring email required
domainstring required
kind'shared' | 'custom' required

shared: on the platform's shared inbox domain, no DNS needed. custom: on a domain of your own.

displayNamestring nullable

Used as the From name on mail sent from this inbox.

status'active' | 'paused' | 'deleted' required
securityMode'off' | 'tag' | 'hold'

Scan received mail for attempts to manipulate an AI agent. tag: deliver now, label security-review if flagged. hold: withhold from the agent (no email.received, hidden from reads) until the scan clears it or a project key releases it.

clientIdstring nullable

Your idempotency key from creation, if you passed one.

metadataobject nullable
createdAtstring date-time required
updatedAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.