Mailboxes

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 journey 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.

Create a mailbox

Reserves a globally unique name. The deliverable address is {name}@agents.aiqaramba.com and is returned as `address`. Name must be 1 to 40 characters, lowercase letters, digits, or hyphens, with no leading or trailing hyphen.

Parameters

Status Codes

Response Body

{
  "name": "acme-staging",
  "address": "acme-staging@agents.aiqaramba.com",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-15T10:30:00Z"
}

List mailboxes

Parameters

Status Codes

Response Body

{
  "mailboxes": [
    {
  "name": "acme-staging",
  "address": "acme-staging@agents.aiqaramba.com",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-15T10:30:00Z"
}
  ]
}

Get a mailbox by name

Parameters

Status Codes

Response Body

{
  "name": "acme-staging",
  "address": "acme-staging@agents.aiqaramba.com",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-15T10:30:00Z"
}

Delete a mailbox

Removes the mailbox and every email stored against it. Any journey or test run that referenced the mailbox is detached automatically. The name is freed and may be re-claimed by anyone.

Parameters

Status Codes

List emails received by a mailbox

Returns the most recently received messages first. Each email includes the plain-text and HTML bodies as delivered — the platform does not modify them.

Parameters

Status Codes

Response Body

{
  "emails": [
    {
  "id": "cc0e8400-e29b-41d4-a716-446655440000",
  "sender": "noreply@vendor.example",
  "recipient": "acme-staging@agents.aiqaramba.com",
  "subject": "Confirm your email",
  "body_text": "Click the link to confirm: https://app.example/confirm?token=abc",
  "body_html": "<p>Click the link to confirm: <a href=\"https://app.example/confirm?token=abc\">Confirm</a></p>",
  "received_at": "2026-05-15T10:32:14Z",
  "created_at": "2026-05-15T10:32:14Z"
}
  ]
}