Email Inboxes

The email_inbox object

A routable email inbox on a verified domain.

Mail sent to this address is threaded into a conversation: the first message of a thread opens a new customer case, and later messages in the same thread join the conversation it already created. Replies to the customer go back out from this address, and the bound agent — if there is one — can draft or send them.

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_domainnullable

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_definitionnullable

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.

Used by

POSTCreate Email InboxEmail Inboxes PATCHUpdate Email InboxEmail Inboxes GETList Email InboxesEmail Inboxes GETGet Email InboxEmail Inboxes DELETEDelete Email InboxEmail Inboxes

email_inbox 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": {
      "id": "rl_3xknmfqflhvb",
      "object": "role",
      "name": "Admin",
      "type": "admin",
      "owner": {
        "object": "owner",
        "type": "account",
        "account": {
          "id": "ac_ykxoradjoeb3",
          "object": "account",
          "name": "Acme Inc.",
          "default_billing_address": null,
          "default_shipping_address": null,
          "branding": null,
          "portal": null,
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        }
      },
      "permissions": [
        "customers:create",
        "customers:read",
        "customers:update",
        "customers:delete"
      ],
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    },
    "config": {
      "object": "agent_definition_config",
      "system_prompt": "You are an order processing agent. Parse incoming emails and create draft orders.",
      "tier": "high",
      "temperature": 0.2,
      "trigger_config": {
        "object": "trigger_config",
        "cron_schedule": null,
        "timezone": null,
        "event_filters": [
          "email.received"
        ]
      },
      "endpoint_tool_slugs": [
        "create_account_group"
      ],
      "endpoint_tool_review": {
        "create_account_group": true
      }
    },
    "tools": {
      "object": "list",
      "page_info": {
        "next_page_url": null,
        "previous_page_url": null,
        "has_next_page": false,
        "has_prev_page": false
      },
      "data": [
        {
          "id": "agdftl_iyc1asmsg1pu",
          "object": "agent_definition_tool",
          "tool": {
            "object": "available_tool",
            "slug": "read_doc",
            "category": "built_in",
            "name": "Lookup Customer",
            "description": "Look up a customer by their email address.",
            "config_schema": null,
            "required_permissions": [
              "customers:read"
            ],
            "required_role_type": null,
            "mutating": false
          },
          "review_requirement": "not_required",
          "config": {},
          "sort_order": 0
        }
      ]
    },
    "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": {
      "id": "rl_3xknmfqflhvb",
      "object": "role",
      "name": "Admin",
      "type": "admin",
      "owner": {
        "object": "owner",
        "type": "account",
        "account": {
          "id": "ac_ykxoradjoeb3",
          "object": "account",
          "name": "Acme Inc.",
          "default_billing_address": null,
          "default_shipping_address": null,
          "branding": null,
          "portal": null,
          "created_at": "2026-05-10T00:00:00Z",
          "updated_at": "2026-05-10T00:23:00Z"
        }
      },
      "permissions": [
        "customers:create",
        "customers:read",
        "customers:update",
        "customers:delete"
      ],
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    },
    "config": {
      "object": "agent_definition_config",
      "system_prompt": "You are an order processing agent. Parse incoming emails and create draft orders.",
      "tier": "high",
      "temperature": 0.2,
      "trigger_config": {
        "object": "trigger_config",
        "cron_schedule": null,
        "timezone": null,
        "event_filters": [
          "email.received"
        ]
      },
      "endpoint_tool_slugs": [
        "create_account_group"
      ],
      "endpoint_tool_review": {
        "create_account_group": true
      }
    },
    "tools": {
      "object": "list",
      "page_info": {
        "next_page_url": null,
        "previous_page_url": null,
        "has_next_page": false,
        "has_prev_page": false
      },
      "data": [
        {
          "id": "agdftl_iyc1asmsg1pu",
          "object": "agent_definition_tool",
          "tool": {
            "object": "available_tool",
            "slug": "read_doc",
            "category": "built_in",
            "name": "Lookup Customer",
            "description": "Look up a customer by their email address.",
            "config_schema": null,
            "required_permissions": [
              "customers:read"
            ],
            "required_role_type": null,
            "mutating": false
          },
          "review_requirement": "not_required",
          "config": {},
          "sort_order": 0
        }
      ]
    },
    "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"
}

Email Inboxes

Attributes

Used by