Mailboxes

A mailbox is a real email address your agents can read. Every message delivered to `{name}@agents.aiqaramba.com` is stored against the matching mailbox and exposed via the API. Attach a mailbox to a test or a test run to grant that run read access to the inbox, useful for magic links, verification codes, and signup confirmations. Mailboxes are read-only: there is no API to send mail.

Overview

A mailbox is a real, deliverable email address you create on the platform ({name}@agents.aiqaramba.com). Anything sent to that address is stored against the mailbox and can be read back through the API. Mailbox names are unique across the entire platform on a first-come-first-served basis.

Mailboxes are read-only: the platform receives mail, it never sends mail. There is no API to compose or dispatch a message.

Attaching mailboxes

Attach a mailbox to a test or directly to a one-off test run. Every run with an attached mailbox is told which addresses it has access to and is given the ability to read the inbox while it works. Test runs without any attached mailbox have no email access at all; attachment is the gate.

How a mailbox is used during a run is decided contextually by the run's prompt. A prompt that says “confirm your account through the verification email” will most likely have the agent check the inbox; one that doesn't mention email is unlikely to touch the mailbox.

GET /api/v1/mailboxes

List mailboxes

Parameters

Parameter	Type	In	Required	Description
`limit`	integer	query	No	Maximum number of results to return.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/mailboxes" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	The authenticated tenant's mailboxes, newest first.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`mailboxes`	object[]
`mailboxes[].name`	string
`mailboxes[].address`	string
`mailboxes[].tenant_id`	uuid
`mailboxes[].created_at`	date-time

POST /api/v1/mailboxes

Create a mailbox

Reserves a globally unique mailbox name and returns its deliverable address.

Request Body (application/json)

Field	Type	Required	Description
`name`	string	Yes	Name to normalize and reserve as the address local-part.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/mailboxes" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<string>"
  }'

Status Codes

Code	Description
`201`	Mailbox created.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.

Response Fields (201)

Field	Type	Description
`name`	string
`address`	string
`tenant_id`	uuid
`created_at`	date-time

GET /api/v1/mailboxes/{name}

Get a mailbox

Parameters

Parameter	Type	In	Required	Description
`name`	string	path	Yes	Globally unique mailbox name.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/mailboxes/<name>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Mailbox found.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`name`	string
`address`	string
`tenant_id`	uuid
`created_at`	date-time

DELETE /api/v1/mailboxes/{name}

Delete a mailbox

Deletes the mailbox, its stored emails, and its agent and test attachments.

Parameters

Parameter	Type	In	Required	Description
`name`	string	path	Yes	Globally unique mailbox name.

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/mailboxes/<name>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Mailbox deleted.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

GET /api/v1/mailboxes/{name}/emails

List emails received by a mailbox

Returns the most recently received messages first.

Parameters

Parameter	Type	In	Required	Description
`limit`	integer	query	No	Maximum number of results to return.
`name`	string	path	Yes	Globally unique mailbox name.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/mailboxes/<name>/emails" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Emails received by the mailbox.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`emails`	object[]
`emails[].id`	uuid
`emails[].sender`	string
`emails[].recipient`	string
`emails[].subject`	string
`emails[].body_text`	string
`emails[].body_html`	string
`emails[].received_at`	date-time
`emails[].created_at`	date-time