Email Intake

Field Service includes an email intake processor that can create an FSM Request from inbound mail. The processor is intentionally lean: it creates the request and leaves triage, customer matching, and structured fields to the dispatcher.

/fsm/settings stores a workspace custom intake alias. Signed inbound email sent to that exact alias creates an FSM request before the support-ticket fallback runs.

Current alias pattern

The legacy processor still recognizes these built-in recipient patterns:

Pattern	Use for
`service@yourdomain.tld`	Default field-service intake.
`service+anything@yourdomain.tld`	Team or region variants, such as `service+north@...`.

For production routing, configure a unique custom alias in FSM Settings, such as repairs@yourdomain.tld. The default service@workestra.app value is not claimed globally because it cannot identify a single workspace by itself.

What happens after a match

Customer emails service@...
  -> inbound email processor matches the recipient
  -> fsm_requests row is created
  -> request appears at /fsm/requests in status new

The processor creates a request with:

Field	Source
`source`	`email`
`summary`	Email subject, or `(no subject)`
`description`	Plain-text body, or HTML stripped to text
`source_inbound_item_id`	`null` in the current email path
`contact_id` / `company_id`	Not auto-matched yet
`service_type` / `preferred_window` / `location_*`	Not parsed from the email body yet

The dispatcher fills in structured fields during triage and links the customer when needed.

Deduplication

The inbound email path deduplicates by the email Message-ID stored in synced_emails.internet_message_id. Replaying the same webhook payload should not create duplicate FSM requests.

What is not auto-parsed yet

The processor does not yet:

Parse a structured intake form from the email body.
Auto-match the sender email to a CRM contact.
Promote attachments to the request page.
Apply routing rules by region, service type, or customer.
Thread customer replies onto an existing FSM request.

For richer intake today, use the Inbound module with a routing rule that emits create_fsm_request.

Channel intake

Non-email channels can create FSM requests through the shared inbound action handler registered by src/modules/fsm/integrations/inbound-handler.ts.

Example rule:

when channel = whatsapp
  and to_handle = +1XXXXXXXXXX
do create_fsm_request

The original message remains in the channel or inbound substrate for audit, while FSM receives a request row for dispatcher triage.

Troubleshooting

No requests are showing up

Confirm the inbound webhook or mailbox sync is running.
Confirm the recipient currently matches service@... or service+...@....
Confirm the message has a Message-ID header.

A request appears with (no subject)

The sending client did not include a subject. Edit the request summary during triage.

A custom alias is saved but not creating requests

Confirm the incoming To address exactly matches the saved alias after lowercase normalization, and that the inbound webhook is the signed Workestra email webhook. Custom aliases are unique across workspaces; duplicate custom aliases are rejected by the database.

Requests - what these emails become
Settings - stored intake alias and dispatch policy
Inbound settings - webhook, form, and routing configuration