AGagentmail-to
pods > inboxes

Create Inbox

Changed on

CLI:

agentmail pods inboxes create --pod-id <pod_id> --username myagent --domain example.com
post/v0/pods/{pod_id}/inboxes

Request

  • Base URL
    https://api.agentmail.to
  • URL
    https://api.agentmail.to/v0/pods/{pod_id}/inboxes
  • Auth
    HTTP bearer

Path parameters

pod_idstring required

ID of pod.

Request body

usernamestring

Username of address. Randomly generated if not specified.

domainstring

Domain of address. Must be a verified domain, or any subdomain of a verified domain that has subdomains enabled (e.g., bot.example.com). Defaults to agentmail.to.

display_namestring

Display name: Display Name <username@domain.com>.

client_idstring

Client ID of inbox.

status'active' | 'paused'

Whether the inbox sends and receives mail. paused stops both: sends return 403 with code inbox_paused, and incoming mail is not delivered and not bounced, then or on resume. Mail already in the inbox, its drafts, and its API keys are kept. Set active to resume.

pause_atstring date-time

When the inbox pauses itself. Within about five minutes after this time, the inbox becomes paused exactly as if status had been set to paused, and pause_at is cleared. Must be in the future; returned in UTC. A manual pause or resume does not change it.

metadataInboxesMetadata

Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and string values are each limited to 256 characters. When updating metadata, send a key with a null value to remove that key.

Response

Response with status 200

pod_idstring required

ID of pod.

inbox_idstring required

The ID of the inbox.

emailstring required

Email address of the inbox.

display_namestring

Display name: Display Name <username@domain.com>.

client_idstring

Client ID of inbox.

status'active' | 'paused'

Whether the inbox sends and receives mail. paused stops both: sends return 403 with code inbox_paused, and incoming mail is not delivered and not bounced, then or on resume. Mail already in the inbox, its drafts, and its API keys are kept. Set active to resume.

pause_atstring date-time

When the inbox pauses itself. Within about five minutes after this time, the inbox becomes paused exactly as if status had been set to paused, and pause_at is cleared. Must be in the future; returned in UTC. A manual pause or resume does not change it.

metadataInboxesMetadata

Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and string values are each limited to 256 characters. When updating metadata, send a key with a null value to remove that key.

updated_atstring date-time required

Time at which inbox was last updated.

created_atstring date-time required

Time at which inbox was created.

Changes

  • a9792efe7bdfRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 074503eed059Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status