Inbound Email Routing

Relay can receive incoming emails and automatically route them to PSA (as tickets or notes), CRM (as activities), or Portal (as client replies). This enables email-based workflows where clients reply to notifications and their responses flow into the right system.

How It Works

Incoming Email → SES Receipt Rule → S3 Storage → SNS → Relay Inbound Handler → PSA/CRM/Portal

1. An email is sent to an address on the inbound routing domain
2. SES receives the email and stores the raw content in S3
3. SNS notifies Relay's inbound processing endpoint
4. Relay parses the email, determines the routing target, and forwards it

Routing Domain

Inbound emails are received at addresses on relay.theonestack.com. The routing is determined by the local part (everything before the @) of the recipient address.

Routing Patterns

Address Pattern	Routes To	Action
ticket+{ticket_id}@relay.theonestack.com	PSA	Adds a note to existing ticket {ticket_id}
support+{tenant_id}@relay.theonestack.com	PSA	Creates a new ticket for the tenant
crm+{contact_id}@relay.theonestack.com	CRM	Logs an activity against the contact
portal+{ticket_id}@relay.theonestack.com	Portal	Adds the client's reply to their ticket
support@{custom-domain}	PSA	Creates a new ticket (custom domain routing)

Examples

Client replies to a ticket notification: Your PSA sends a ticket update notification with Reply-To: [email protected]. When the client replies, Relay routes the reply as a note on ticket #1234.

Client sends a new support request: A client emails [email protected]. Relay creates a new PSA ticket for the tenant identified by abc123.

Custom domain support email: A client emails [email protected] (which has MX records pointing to SES). Relay looks up the domain's tenant and creates a new PSA ticket.

Thread Matching

Relay uses the In-Reply-To email header to match incoming emails to previously sent messages. When a reply arrives:

1. Relay checks the In-Reply-To header against sent email message IDs
2. If a match is found, the reply is threaded with the original conversation
3. This enables automatic routing even without address-based patterns

This means clients can simply hit "Reply" on any Relay-sent email and the response is automatically routed to the correct system and record.

Setting Up Inbound Routing

For the Default Relay Domain

Inbound routing on relay.theonestack.com is configured automatically. Set the appropriate reply-to addresses when sending emails from your integrations.

For Custom Domains

To enable inbound routing on your own domain:

1. Verify the domain in Relay (see Domain Setup)
2. Add MX records pointing to SES:

Type	Name	Priority	Value
MX	yourmsp.com	10	inbound-smtp.us-east-1.amazonaws.com

3. Enable inbound routing in the domain settings
4. Configure routing rules (create ticket from, ticket reply prefix)

⚠️Adding MX records changes where email for your domain is delivered. If you already receive email on this domain (e.g., user mailboxes), use a subdomain like support.yourmsp.com instead.

Inbound Email Storage

All inbound emails are stored in two locations:

• S3 bucket — Raw email content (headers, body, attachments) for archival
• Cosmos DB — Parsed metadata in the inbound_emails container (sender, subject, routing result, timestamp)

Bus Events

When an inbound email is processed, Relay emits a relay.email.inbound Bus event containing:

• Sender address
• Recipient address
• Subject
• Routing target (PSA/CRM/Portal)
• Action taken (ticket created, note added, activity logged)

Integrations Required

Inbound routing requires these integrations to be configured:

Target	Required Environment Variables
PSA	PSA_API_URL, INTEGRATION_KEY
CRM	CRM_API_URL, INTEGRATION_KEY
Portal	PORTAL_API_URL, INTEGRATION_KEY

If an integration endpoint is not configured, inbound emails for that target are stored in the inbound_emails container but not forwarded. They can be manually processed later.

Common Use Cases

Ticket reply workflow:

1. PSA sends a ticket notification via Relay with Reply-To: [email protected]
2. Client replies to the email
3. Relay receives the reply, routes it to PSA as a note on ticket #1234
4. The technician sees the client's response directly in the ticket

New ticket from email:

1. Client emails [email protected] (or [email protected])
2. Relay creates a new PSA ticket with the email subject as the title and body as the description
3. The technician gets notified of the new ticket

CRM activity logging:

1. CRM sends a follow-up reminder via Relay with Reply-To: [email protected]
2. Client replies
3. Relay logs the reply as an activity on the CRM contact record