Integrations

Relay connects with multiple products in The One Stack ecosystem. It serves as the email infrastructure layer — other products send transactional emails through Relay and receive inbound emails via its routing engine.

Hub

Direction	What Syncs
Hub → Relay	SSO authentication, user identity, organization context
Relay → Hub	Session validation on every authenticated request

How it works: Users access Relay through Hub SSO. When you click Relay in the Hub waffle menu, Hub sends a JTI (JWT Token ID) to Relay's portal SSO endpoint, which validates it against Hub and creates a local session.

Setup: Automatic — configured during platform deployment. Requires PORTAL_SSO_SECRET and HUB_API_URL environment variables on the Relay API.

PSA

Direction	What Syncs
PSA → Relay	Ticket notification emails, SLA breach alerts
Relay → PSA	Inbound email replies create tickets or add notes

How it works:

• Outbound: PSA calls Relay's send API to deliver ticket notifications, assignment alerts, and SLA breach notices to clients and technicians
• Inbound: Emails to ticket+{id}@relay.theonestack.com add notes to existing tickets. Emails to support+{tenant}@relay.theonestack.com create new tickets.

Setup: PSA needs a Relay API key with send scope. Relay needs PSA_API_URL and INTEGRATION_KEY for inbound routing.

If misconfigured: Outbound — ticket notifications won't send, clients won't receive updates. Inbound — client email replies won't appear in tickets; they'll be stored in Relay's inbound archive instead.

CRM

Direction	What Syncs
CRM → Relay	Contact follow-up emails, campaign sends
Relay → CRM	Inbound replies log as activities on contact records

How it works:

• Outbound: CRM uses Relay to send follow-up emails and communications to contacts
• Inbound: Emails to crm+{contact_id}@relay.theonestack.com create activity entries on the contact

Setup: CRM needs a Relay API key with send scope. Relay needs CRM_API_URL and INTEGRATION_KEY for inbound routing.

If misconfigured: Outbound — CRM emails won't send. Inbound — client replies won't log as activities; stored in inbound archive.

Portal

Direction	What Syncs
Portal → Relay	Ticket submission confirmations, status update notifications
Relay → Portal	Client email replies route to their ticket thread

How it works:

• Outbound: Portal sends confirmation emails when clients submit or update tickets
• Inbound: Emails to portal+{ticket_id}@relay.theonestack.com add the client's reply to their Portal ticket thread

Setup: Portal needs a Relay API key with send scope. Relay needs PORTAL_API_URL and INTEGRATION_KEY for inbound routing.

If misconfigured: Outbound — clients won't receive ticket confirmations. Inbound — client email replies won't thread into Portal tickets.

Books

Direction	What Syncs
Relay → Books	Email usage counts for billing

How it works: Relay reports email volume to Books for usage-based billing. The background billing usage reporter runs on a timer and sends daily counts.

Setup: Requires HUB_BILLING_API_URL environment variable on Relay background function app.

If misconfigured: Email sending continues to work, but usage won't be tracked for billing purposes.

The One Bus

Direction	What Syncs
Relay → Bus	Email lifecycle events

How it works: Relay emits Bus events for key actions:

Event	When
relay.email.sent	Email submitted to SES
relay.email.bounced	Email bounced
relay.email.complained	Spam complaint received
relay.alert.bounce_rate	Bounce rate exceeds threshold
relay.email.inbound	Inbound email received and routed

Other products can subscribe to these events for real-time notifications.

Setup: Requires BUS_API_URL and BUS_INTEGRATION_KEY environment variables.

If misconfigured: Email sending works, but no events are emitted. Other products won't receive real-time email status updates.

AWS SES

Direction	What Syncs
Relay → SES	Outbound email delivery
SES → Relay	Delivery/bounce/complaint/open/click events via SNS webhooks

How it works: Relay is a managed layer on top of SES. All emails are sent via the SES API. SES event notifications flow back through SNS to Relay's webhook endpoint.

Setup: Requires AWS IAM credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), SES configuration set, and SNS topic subscription.

If misconfigured: No emails will send. Check SES identity verification status and IAM permissions.

Integration Summary

Product	Outbound (Relay sends)	Inbound (Relay receives)	Required Keys
Hub	—	SSO login	PORTAL_SSO_SECRET, HUB_API_URL
PSA	Ticket notifications	Ticket creation/notes	PSA_API_URL, INTEGRATION_KEY
CRM	Contact emails	Activity logging	CRM_API_URL, INTEGRATION_KEY
Portal	Confirmations	Client replies	PORTAL_API_URL, INTEGRATION_KEY
Books	—	Billing usage reports	HUB_BILLING_API_URL
Bus	—	Event emission	BUS_API_URL, BUS_INTEGRATION_KEY
SES	Email delivery	Lifecycle events	AWS IAM credentials