List Mail contacts

Outcome

Read mailbox contacts with an optional text query and result limit.

Before you start

• Verify the intended environment, credential and authorized organization context before discovery.
• Discover Mail, the exact action and its messages:read permission. Select an accessible canonical workspace and discover the mailbox there; pass workspace resource context separately from mailboxId.

Discover the target

• Run credential-scoped Mail discovery, select an authorized canonical workspace and list Mail mailboxes there.
• Discover message, thread, folder and attachment identifiers through the related reads; never reuse fixture identifiers or another organization’s records.

topolo whoami --json
topolo apps get topolo-mail --json
topolo actions get app_topolo_mail.contacts.list --json
topolo workspaces list topolo-mail --json
topolo actions get app_topolo_mail.mailboxes.collection.list --json

Use the currently discovered mailbox-collection action to resolve mailboxId in the selected workspace. Discover and validate its schema before execution. Fixture IDs below do not grant access.

Request

Create payload.json with the current schema and discovered identifiers. This action is a read; do not use confirmation to authorize unrelated sends or data changes.

topolo actions validate app_topolo_mail.contacts.list --data @payload.json --json
topolo actions plan app_topolo_mail.contacts.list --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --json
topolo actions call app_topolo_mail.contacts.list --resource-type workspace --resource-id <discovered-workspace-id> --data @payload.json --json

For MCP, discover with topolo_get_action, validate with topolo_validate_action, plan with topolo_plan_action and execute with topolo_read_action. Pass resourceType workspace and the discovered resourceId separately from input. A service/action absent from the credential-scoped catalog blocks that operation.

Input fields

Effects

• Reads mailbox-derived contacts without creating contacts or sending outreach.

Interpret the response

data.contacts wraps the mailbox contact-query result. It is not the platform People/CRM contact directory and does not authorize contacting any recipient. No cursor is published for this action.

Worked requests and responses

Successful fixture read · HTTP 200

Input

{
  "mailboxId": "mbx_mail_fixture",
  "q": "sender",
  "limit": 5
}

SDK response or error

{
  "success": true,
  "data": {
    "contacts": [
      {
        "email": "sender@example.test",
        "name": "Fixture sender",
        "count": 1
      }
    ]
  }
}

Refused requests

unauthenticated · HTTP 401

Input

{
  "mailboxId": "mbx_mail_fixture",
  "q": "sender",
  "limit": 5
}

SDK response or error

{
  "code": "auth_error",
  "status": 401,
  "message": "Fixture authentication refused"
}

HTTP body and transport

{
  "contentType": "application/json",
  "contentDisposition": null,
  "body": {
    "success": false,
    "error": {
      "message": "Fixture authentication refused"
    }
  }
}

permission denied · HTTP 403

Input

{
  "mailboxId": "mbx_mail_fixture",
  "q": "sender",
  "limit": 5
}

SDK response or error

{
  "code": "permission_denied",
  "status": 403,
  "message": "TopoloMail permission denied"
}

HTTP body and transport

{
  "contentType": "application/json",
  "contentDisposition": null,
  "body": {
    "success": false,
    "error": {
      "message": "TopoloMail permission denied"
    }
  }
}

other organization · HTTP 403

Input

{
  "mailboxId": "mbx_mail_fixture",
  "q": "sender",
  "limit": 5
}

SDK response or error

{
  "code": "permission_denied",
  "status": 403,
  "message": "Mailbox does not belong to your organization"
}

HTTP body and transport

{
  "contentType": "application/json",
  "contentDisposition": null,
  "body": {
    "success": false,
    "error": {
      "message": "Mailbox does not belong to your organization"
    }
  }
}

other workspace · HTTP 404

Input

{
  "mailboxId": "mbx_mail_fixture",
  "q": "sender",
  "limit": 5
}

SDK response or error

{
  "code": "http_error",
  "status": 404,
  "message": "Mailbox not found"
}

HTTP body and transport

{
  "contentType": "application/json",
  "contentDisposition": null,
  "body": {
    "success": false,
    "error": {
      "message": "Mailbox not found"
    }
  }
}

unknown mailbox · HTTP 404

Input

{
  "mailboxId": "mbx_missing_fixture",
  "q": "sender",
  "limit": 5
}

SDK response or error

{
  "code": "http_error",
  "status": 404,
  "message": "Mailbox not found"
}

HTTP body and transport

{
  "contentType": "application/json",
  "contentDisposition": null,
  "body": {
    "success": false,
    "error": {
      "message": "Mailbox not found"
    }
  }
}

Verify the result

• Compare the returned mailbox/message/thread identifiers with the selected mailbox and canonical workspace; an HTTP success alone is not the intended-result check.
• Use the response interpretation above and related published reads to verify the result. Do not infer a provider outcome, send completion or encryption guarantee from this read.

Recover

This action requests no delivery or deletion. Preserve failures and recover only through the published read/error guidance; no rollback mutation is needed. Inbox/snooze reads can remove expired overlays and folder reads can synchronize provider cache, as stated in effects.

• HTTP 401 auth_error: Authenticate again in the intended environment and context, then repeat identity and discovery. Do not change organization automatically.
• HTTP 403 permission_denied: Stop and inspect the exact permission or organization refusal. Connection reads additionally require mailbox management permission. Do not broaden access or switch credentials automatically.
• HTTP 404 http_error: Rediscover the mailbox and child identifiers in the same authorized canonical workspace. A missing or differently scoped mailbox is not permission to guess another ID.

Related actions

• List Mail messages

Evidence and limits

• Actual exported Mail API route dispatcher, handlers, authorization branches, contract validation and SDK 0.23.13 response projection; shipped control, delivery and tracking migrations execute against in-memory SQLite through the D1 adapter.

• Verified identity and workspace grants are supplied fixtures; no live OAuth, API-key introspection, CLI/MCP gateway or deployed environment is proved.

• Mailbox Durable Object/tool responses and content unprotection are fixture ports. No provider sync, encryption custody, notification or delivery outcome is proved. External network egress is refused.

These examples use synthetic mailboxes, messages and identities. They demonstrate request and response behavior without delivering email or contacting a live provider. Discover the available action and its current contract before using it with your own authorized workspace.