List Email Inboxes

Beta

GET/v1/messaging/email-inboxes

This endpoint is idempotent. Learn more

Returns the account's email inboxes across every registered domain.

Every inbox is returned in a single response; this list is not paginated.

Permissions requiredValues:messaging:read

The role behind your API key or agent must grant every one of these permissions.

include[]optional arrayenumValues:email_domainagent_config

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of email_inbox

Resources in this page.

idstring

Email inbox ID.

objectstringenumValues:email_inbox

Resource type identifier.

statusstringenumValues:activedisabled

Whether the inbox is currently accepting mail.

active: inbound mail is threaded into a conversation.
disabled: the inbox stays provisioned and keeps its history, but inbound mail is dropped without being threaded.

email_domainemail_domainExpandablenullable

The domain this inbox belongs to.

idstring

Email domain ID.

objectstringenumValues:email_domain

Resource type identifier.

domainstring

The fully-qualified domain name (e.g. support.acme.com).

statusstringenumValues:pendingverifiedfailed

Verification status.

pending: registered and awaiting DKIM confirmation.
verified: DKIM confirmed; the domain can send mail.
failed: verification could not be completed.

Inboxes can only be created on a verified domain.

dkim_tokensarray of string

The DKIM tokens that must be published in your DNS before the domain can be verified.

Publish each token as a CNAME record on the domain, then call the verify action to confirm them.

verified_atstring (date-time)nullable

When the domain's DKIM verification was confirmed.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

addressstring

The full inbox address (e.g. support@acme.com).

forwarding_addressstringnullable

A forwarding address on an OpenMRP-owned domain that also routes to this inbox.

Use this when your domain's mail is hosted elsewhere (e.g. Google Workspace, Microsoft 365) and you cannot point its MX records at OpenMRP: forward mail from address to this address instead, and it will still be threaded into a conversation.

from_namestringnullable

The display name used in the From header of outbound mail.

agent_configagent_definitionExpandablenullable

The agent that handles mail for this inbox.

The agent is seated on every conversation this inbox opens, so it can read the thread and draft or send replies.

idstring

Agent definition ID.

objectstringenumValues:agent_definition

Resource type identifier.

definition_typestringenumValues:systemcustom

Whether the agent is provided by OpenMRP or created in this account.

system: provided by OpenMRP; cannot be edited or deleted.
custom: created by a user in this account.

category_codestring

Category grouping for the agent (e.g. order_processing), used to organize agents in the UI.

trigger_typestringenumValues:scheduledmanualevent

How runs of this agent are initiated.

scheduled: runs on a cron schedule (see config.trigger_config.cron_schedule).
event: runs in response to platform events (see config.trigger_config.event_filters).
manual: runs only when explicitly invoked.
chat: runs in response to a chat message; the run is linked to a conversation and posts its reply back into it.

namestring

Human-readable name of the agent.

slugstring

URL-friendly identifier for the agent.

Unique within the account.

descriptionstringnullable

Description of what the agent does.

editabilitystringenumValues:editableread_only

Whether this agent definition can be edited.

Always read_only for system definitions.

statusstringenumValues:activeinactive

Whether this agent is enabled for the current account.

Activation is per-account: a system agent shared across accounts can be active for one account and inactive for another. An inactive agent cannot be triggered.

rolerolenullable

Role defining the permissions the agent operates with.

The agent acts as its own actor, and everything it does is authorized against this role — it can never reach data or actions the role does not grant. An agent with no role cannot execute: its runs fail immediately.

Always returned as null in this endpoint.

configagent_definition_confignullable

Agent-level configuration controlling LLM behavior and trigger settings.

Always returned as null in this endpoint.

toolslistnullable

Tools attached to this agent.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

agent_trigger_policystringnullableenumValues:mentionkeywordalways

When the bound agent runs on incoming mail.

mention: only when the agent is @mentioned, matched against its trigger keywords.
keyword: when the mail contains any of the configured trigger keywords.
always: on every incoming message.

When no policy is set the agent runs on every incoming message, since email has no reliable @mention convention.

agent_trigger_keywordsarray of string

The keywords that decide whether the agent runs on an incoming message.

Under the keyword policy a keyword matches anywhere in the message; under mention it only counts where it is prefixed with @.

group_idstringnullable

The messaging group (roster) whose members are added to every conversation this inbox opens.

Its members join each new email thread so the team can read, edit, and approve replies alongside the bound agent. Membership is captured when the thread opens, so later edits to the group only affect conversations opened after the change.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

200

Successful response for List Email Inboxes

List Email Inboxes

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listEmailInbox = await client.messaging.emailInboxes.list();

console.log(listEmailInbox.data);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const listEmailInbox = await client.messaging.emailInboxes.list();

console.log(listEmailInbox.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/messaging/email-inboxes?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoiZW1pbmJfMnM5a29icjlzN3RwIiwiZCI6ImYifQ.GSwTue4k5a8-oZJC8Bhaem-c-KHDETMUqUbO0zawSG0",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "eminb_2s9kobr9s7tp",
      "object": "email_inbox",
      "status": "active",
      "email_domain": {
        "id": "emdom_2rk3omr8vshb",
        "object": "email_domain",
        "domain": "support.acme.com",
        "status": "pending",
        "dkim_tokens": [
          "abc123._domainkey.support.acme.com",
          "def456._domainkey.support.acme.com"
        ],
        "verified_at": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      },
      "address": "support@acme.com",
      "forwarding_address": null,
      "from_name": "Acme Support",
      "agent_config": {
        "id": "agdf_ah7tkyfxk8jl",
        "object": "agent_definition",
        "definition_type": "system",
        "category_code": "order_processing",
        "trigger_type": "event",
        "name": "Email Order Agent",
        "slug": "email_order",
        "description": "Processes incoming emails and creates draft orders.",
        "editability": "read_only",
        "status": "inactive",
        "role": null,
        "config": null,
        "tools": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      },
      "agent_trigger_policy": "always",
      "agent_trigger_keywords": [],
      "group_id": null,
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/messaging/email-inboxes?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoiZW1pbmJfMnM5a29icjlzN3RwIiwiZCI6ImYifQ.GSwTue4k5a8-oZJC8Bhaem-c-KHDETMUqUbO0zawSG0",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "id": "eminb_2s9kobr9s7tp",
      "object": "email_inbox",
      "status": "active",
      "email_domain": {
        "id": "emdom_2rk3omr8vshb",
        "object": "email_domain",
        "domain": "support.acme.com",
        "status": "pending",
        "dkim_tokens": [
          "abc123._domainkey.support.acme.com",
          "def456._domainkey.support.acme.com"
        ],
        "verified_at": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      },
      "address": "support@acme.com",
      "forwarding_address": null,
      "from_name": "Acme Support",
      "agent_config": {
        "id": "agdf_ah7tkyfxk8jl",
        "object": "agent_definition",
        "definition_type": "system",
        "category_code": "order_processing",
        "trigger_type": "event",
        "name": "Email Order Agent",
        "slug": "email_order",
        "description": "Processes incoming emails and creates draft orders.",
        "editability": "read_only",
        "status": "inactive",
        "role": null,
        "config": null,
        "tools": null,
        "created_at": "2026-05-10T00:00:00Z",
        "updated_at": "2026-05-10T00:23:00Z"
      },
      "agent_trigger_policy": "always",
      "agent_trigger_keywords": [],
      "group_id": null,
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  ]
}

List Email Inboxes

Authorization

Query Parameters

Returns

Responses