Introduction to Email Inbox

An email inbox connects a mailbox to omnichannel, so emails sent to an address become Rocket.Chat conversations and agents can reply from the workspace. The Email Inbox API lets administrators create, inspect, test, and remove these inbox configurations.

The email inbox object

Email inbox endpoints return an inbox configuration object. A trimmed example from List Email Inbox:

{
  "emailInboxes": [
    {
      "_id": "60197e8ff82d6c83b96c53ff",
      "active": false,
      "name": "Rocket.Chat sample account",
      "email": "info@rocket.chat",
      "department": "GgYvrkAF63aeQmsh4",
      "smtp": { "server": "smtp.gmail.com", "port": 465, "secure": true },
      "imap": { "server": "imap.gmail.com", "port": 993, "secure": true }
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1,
  "success": true
}

Fields you use most often:

• _id: The inbox ID, used to read, update, or delete the inbox.

• email and active: The connected address and whether the inbox is currently processing mail.

• smtp and imap: The outgoing and incoming mail server settings, including credentials.

• department: The omnichannel department that receives conversations from this inbox.

Common workflows

Connect a mailbox to omnichannel

1. Set the email inbox with the address, SMTP and IMAP settings, and target department. The same endpoint updates an existing inbox when you pass its _id.

2. Send a test email to confirm the SMTP settings work.

3. List the inboxes, search by address, or read one by ID to verify the configuration, and delete an inbox to disconnect it.

Conventions

• These are administrative endpoints and require email inbox management permissions; each endpoint page lists its requirements.

• Inbox objects carry mail server credentials — treat responses as sensitive.

• For the corresponding admin UI setup, see the Email Inboxes user guide.