Inbound email processing

Connect incoming email

Customers configure incoming email in Email tickets onboarding or mailbox settings. Connect a supported mailbox, or forward mail to the exact destination shown for your department. Sending-domain verification does not set up incoming mail. Preserve your current provider’s MX records when using forwarding.

The /api/v1/email/inbound route is a platform-to-platform relay endpoint. Its signing secret is managed by Message.com, not a per-workspace secret available in customer settings. Do not point a third-party email provider at this endpoint without an approved relay configuration.

Relay payload

The internal relay requires from, a nonempty to array and messageId. subject and text default to empty strings; html, inReplyTo, references and headers are optional. Arbitrary provider payloads are not accepted without normalization. This generic schema does not accept attachments.

inReplyTo and references are top-level fields used for threading; copying those values only into the headers map does not populate them. messageId is required; this route does not synthesize one.

{
  "from": "Customer <[email protected]>",
  "to": [
    "[email protected]"
  ],
  "subject": "Help with my order",
  "text": "Please help me find my invoice.",
  "messageId": "<[email protected]>",
  "inReplyTo": "<[email protected]>",
  "references": [
    "<[email protected]>"
  ]
}

Relay authentication

The relay sends X-Signature: sha256=<hex>, calculated with HMAC-SHA256 over the exact raw body bytes and the platform relay secret. This is separate from product webhook signing secrets. Never expose the relay secret in a browser or customer integration.

Routing and threading

Recipient addresses and forwarding headers identify the workspace and department. Reply aliases and references to stored email message IDs can identify an existing ticket. There is no subject-only threading guarantee. Duplicate stored message IDs are handled without creating another message.

Recognized bounce senders/subjects and Auto-Submitted or Precedence bulk/list/junk signals can cause an intentional drop. A List-Unsubscribe header alone is not a documented drop condition.

Interpret the result

A processed new message returns HTTP 200 with ok, conversationId and created. HTTP 200 can also acknowledge a duplicate or intentional drop; inspect the response body and incoming-mail diagnostics. Invalid payloads return HTTP 200 with ok:false and error:invalid_payload. Bad signatures return HTTP 401 invalid_signature.

For customer setup QA, send a real test email, verify the intended ticket/department, and reply from the Inbox. A successful DNS check or relay HTTP acknowledgement alone does not demonstrate that complete flow.