Create Email Inbox

Beta

POST/v1/messaging/email-inboxes

Idempotent with Idempotency-Key header. Learn more

Provisions a routable inbox address on a verified domain.

Once created, mail arriving at the address opens a customer case conversation and seats the bound agent and the group's members on it; a reply in a thread that already opened one joins that conversation instead.

Permissions requiredValues:messaging:create

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.

email_domain_idstring

The verified domain this inbox belongs to.

addressstring

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

Its domain part must match the selected domain, which must already be verified. The address is lowercased before it is stored, and it must not already be in use by another inbox.

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.

With no agent bound, mail is still threaded into a conversation for your team, but nothing runs on it automatically.

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.

Leaving this unset makes the agent run 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. Agents in the group are seated to run only when @mentioned, so they do not all fire alongside the inbox's own agent.

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

201

Successful response for Create Email Inbox

Create 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.create({
  address: 'support@acme.com',
  email_domain_id: 'emdom_2rk3omr8vshb',
  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.create({
  address: 'support@acme.com',
  email_domain_id: 'emdom_2rk3omr8vshb',
  agent_config_id: 'agdf_ah7tkyfxk8jl',
  agent_trigger_keywords: ['invoice', 'refund'],
  agent_trigger_policy: 'keyword',
  from_name: 'Acme Support',
});

console.log(emailInbox.id);

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

Create Email Inbox

Authorization

Query Parameters

Request Body

Returns

Responses