Skip to main content

get-mailbox-by-name

Look up ECGrid mailboxes inside one network by a name substring. Use when the caller knows the target network and a fragment of the mailbox name or email (e.g. acme matches acme-prod@example.com and acme-test@example.com). Both networkId and name are required — there is no "all networks / all names" mode. Returns an array of mailbox records (mailboxes) plus a count; the array may be empty when no mailbox in the network matches the substring. This tool deliberately bypasses the response cache so the result always reflects current state. When the caller already knows a specific mailbox's numeric ID, prefer get-mailbox-by-id (cached, faster, single record).

Tool Name​

connectivity_mailbox_get-mailbox-by-name

Auth Level Required​

Any (scoped to caller's APIKey)

Parameters​

ParameterTypeRequiredDescription
request.networkIdintegerYesRestrict results to mailboxes inside one ECGrid network. Positive integer >= 1. If the network ID is unknown, resolve it first via connectivity_network_get-network-by-id.
request.namestringYesCase-insensitive substring filter applied to the mailbox name. May be a full email address (e.g. john.doe@example.com) or a partial name (e.g. acme). 1 to 128 characters.

Response​

Returns a count and a mailboxes array. Each mailbox record has the same shape as the response from get-mailbox-by-id. Always reflects current state — cache is bypassed. An empty array (count: 0) is a valid successful outcome — it means no mailbox in the network matched the substring.

{
  "count": 2,
  "mailboxes": [
    {
      "mailboxId": 142,
      "networkId": 47,
      "name": "acme-prod@example.com",
      "description": "ACME Production Mailbox",
      "status": "Active",
      "useType": "Production",
      "managed": false,
      "ecgridAccount": "acme-prod",
      "defaultAs2Id": 0,
      "ownerUserId": 101,
      "ownerLoginName": "admin@example.com",
      "ownerAuthLevel": "MailboxAdmin",
      "created": "2021-06-01T00:00:00Z",
      "modified": "2026-05-20T14:10:33Z"
    },
    {
      "mailboxId": 143,
      "networkId": 47,
      "name": "acme-test@example.com",
      "description": "ACME Test Mailbox",
      "status": "Active",
      "useType": "Test",
      "managed": false,
      "ecgridAccount": "acme-test",
      "defaultAs2Id": 0,
      "ownerUserId": 101,
      "ownerLoginName": "admin@example.com",
      "ownerAuthLevel": "MailboxAdmin",
      "created": "2021-06-01T00:00:00Z",
      "modified": "2026-05-20T14:10:33Z"
    }
  ]
}

Response Fields​

FieldTypeDescription
countintegerTotal number of mailboxes returned
mailboxesarrayArray of mailbox profile objects
mailboxes[].mailboxIdintegerUnique numeric ECGrid mailbox ID
mailboxes[].networkIdintegerECGrid network this mailbox belongs to
mailboxes[].namestringMailbox name (typically an email address)
mailboxes[].descriptionstringHuman-readable display name for the mailbox
mailboxes[].statusstringLifecycle status (see Status enum)
mailboxes[].useTypestringUse type — Test, Production, or TestAndProduction (see UseType enum)
mailboxes[].managedbooleantrue if this is a managed mailbox
mailboxes[].ecgridAccountstringShort account identifier used internally
mailboxes[].defaultAs2IdintegerECGrid ID of the default AS2 trading partner; 0 if none
mailboxes[].ownerUserIdintegerUser ID of the mailbox owner contact
mailboxes[].ownerLoginNamestringLogin name of the mailbox owner contact
mailboxes[].ownerAuthLevelstringAuth level of the owner (see AuthLevel enum)
mailboxes[].createdstringISO 8601 timestamp when the mailbox was created
mailboxes[].modifiedstringISO 8601 timestamp of the most recent mailbox update

Example Call​

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "connectivity_mailbox_get-mailbox-by-name",
    "arguments": {
      "request": {
        "networkId": 47,
        "name": "acme"
      }
    }
  }
}

Example Prompts​

  • Find mailboxes with "acme" in their name on network 47
  • Search for mailboxes containing "test" on network 7

See Also​