mobieusKnow API: Helpdesk Inbound Email History #291

Revision #291

Approved CURRENT VERSION
All revisions
Author
system
Submitted
Jun 14, 2026 6:59am
Summary
KB drift-audit reconciliation 2026-06-14: corrected to match dev (report deliverables).

API: Helpdesk Inbound Email

mobieusHelp can accept inbound email and turn each message into a ticket. This is a webhook endpoint your email provider (or a relay) posts to. It is secured by a shared secret, not by an API key, so it is separate from the bearer-token /api/v1 surface.

Setup

  1. In Admin → Help → Email Accounts, open your default email account and copy its inbound secret.
  2. Configure your provider to POST each inbound message to: 
    https://{tenant}.mobieus.io/api/helpdesk/inbound-email
  3. Send the secret with every request in the X-Mobieus-Inbound-Secret header (or as a ?secret= query parameter). A request with a missing or wrong secret is rejected with 401.

Payload

POST a JSON body. Recognized fields:

  • from — sender address (a Name <[email protected]> form is parsed; envelope.from is used as a fallback)
  • from_name — sender display name (optional)
  • subject — message subject
  • text — plain-text body
  • html — HTML body
  • message_id — the message's Message-ID (required)
  • in_reply_to, references — threading headers, used to attach replies to an existing ticket
  • headers — an object of raw headers (used to detect auto-replies)

from and message_id are required. If either is missing the endpoint returns 422.

Ticket creation

A new message creates a ticket in the default queue, or appends to the matching ticket when the threading headers point to one. The sender receives a confirmation email with their ticket reference.

## API: Helpdesk Inbound Email

mobieusHelp can accept inbound email and turn each message into a ticket. This is a webhook endpoint your email provider (or a relay) posts to. It is secured by a shared secret, not by an API key, so it is separate from the bearer-token `/api/v1` surface.

### Setup

1. In **Admin → Help → Email Accounts**, open your default email account and copy its inbound **secret**.
2. Configure your provider to POST each inbound message to:
   ```
   https://{tenant}.mobieus.io/api/helpdesk/inbound-email
   ```
3. Send the secret with every request in the `X-Mobieus-Inbound-Secret` header (or as a `?secret=` query parameter). A request with a missing or wrong secret is rejected with `401`.

### Payload

POST a JSON body. Recognized fields:

- `from` — sender address (a `Name <[email protected]>` form is parsed; `envelope.from` is used as a fallback)
- `from_name` — sender display name (optional)
- `subject` — message subject
- `text` — plain-text body
- `html` — HTML body
- `message_id` — the message's `Message-ID` (**required**)
- `in_reply_to`, `references` — threading headers, used to attach replies to an existing ticket
- `headers` — an object of raw headers (used to detect auto-replies)

`from` and `message_id` are required. If either is missing the endpoint returns `422`.

### Ticket creation

A new message creates a ticket in the default queue, or appends to the matching ticket when the threading headers point to one. The sender receives a confirmation email with their ticket reference.