Update Email Inbox

Beta

PATCH/v1/messaging/email-inboxes/{id}

Idempotent with Idempotency-Key header. Learn more

Edits an email inbox's from-name, status, agent configuration, and roster.

Every field except status is merged into the inbox's current settings: a field you omit — and an empty array you send — keeps the value it already has, so this endpoint can change a setting but cannot clear one back to unset. The inbox's address and domain are fixed at creation and cannot be changed here.

Permissions requiredValues:messaging:update

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

idstring

Email inbox ID.

include[]optional arrayenumValues:email_domainagent_config

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

statusstringenumValues:activedisabled

Whether the inbox accepts 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.

from_nameoptional string

Display name for the From header of outbound mail.

agent_config_idoptional string

The agent to bind to this inbox to handle incoming mail.

agent_trigger_policyoptional stringenumValues:mentionkeywordalways

How the bound agent decides whether to run on incoming mail.

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

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

agent_trigger_keywordsoptional array 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_idoptional string

The messaging group (roster) whose members are seated on every conversation this inbox opens.

Must name a group in your own account. Changing it only affects conversations opened afterwards.

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 Update Email Inbox

Update Email Inbox

import OpenMRP from '@openmrp/sdk';

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

const emailInbox = await client.messaging.emailInboxes.update('eminb_2s9kobr9s7tp', {
  status: 'active',
  agent_config_id: 'agdf_ah7tkyfxk8jl',
  agent_trigger_keywords: ['invoice', 'refund'],
  agent_trigger_policy: 'keyword',
  from_name: 'Acme Support',
});

console.log(emailInbox.id);

import OpenMRP from '@openmrp/sdk';

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

const emailInbox = await client.messaging.emailInboxes.update('eminb_2s9kobr9s7tp', {
  status: 'active',
  agent_config_id: 'agdf_ah7tkyfxk8jl',
  agent_trigger_keywords: ['invoice', 'refund'],
  agent_trigger_policy: 'keyword',
  from_name: 'Acme Support',
});

console.log(emailInbox.id);

200 example

{
  "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"
}

{
  "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"
}

Update Email Inbox

Authorization

Path Parameters

Query Parameters

Request Body

Returns

Responses