Email Channel

Turn your existing Gmail or Microsoft 365 inbox into a fully managed support channel. RapiDesq connects via OAuth 2.0, receives emails in real time through push notifications, and automatically converts them into threaded tickets—complete with contact matching, routing, and delivery tracking.

Overview

The email channel bridges your team's email inbox with the RapiDesq ticketing system. Instead of polling for new messages, RapiDesq uses provider-native push mechanisms—Google Cloud Pub/Sub for Gmail and webhook subscriptions for Microsoft—to receive notifications the moment a new email arrives. This architecture delivers near-instant ticket creation without the latency and overhead of periodic polling.

At a high level, the flow works like this:

1. A customer sends an email to your connected inbox (e.g., support@yourcompany.com).
2. The email provider pushes a notification to RapiDesq in real time.
3. RapiDesq fetches the full message from the provider's API, including body, headers, and attachments.
4. The sender is matched to an existing contact by email address, or a new contact is created automatically with the source marked as EMAIL.
5. If the email is a reply within an existing thread (detected via References and In-Reply-To headers), the message is appended to the corresponding ticket.
6. If the email starts a new thread, a new ticket is created—the subject line becomes the ticket title and the email body becomes the description.
7. The ticket is routed to a team queue or a conversation flow based on the connection's routing configuration.
8. Agents reply from RapiDesq, and the response is delivered back to the customer as a standard email from the connected inbox.

Prerequisites

• Admin access to your RapiDesq workspace. Only administrators can connect and configure email channels.
• A Gmail or Microsoft 365 email account that you have permission to authorize with third-party applications. For organizational accounts, your IT administrator may need to pre-approve RapiDesq in the identity provider.
• Understanding of OAuth 2.0 at a conceptual level. RapiDesq uses OAuth 2.0 to obtain delegated access to your mailbox—your email password is never shared with or stored by RapiDesq.
• At least one team or conversation flow configured in RapiDesq to receive the incoming email tickets.

Connecting Gmail

Gmail connections use Google's OAuth 2.0 flow and Google Cloud Pub/Sub for real-time email delivery.

Step-by-step

1. Navigate to Admin > Channels > Email.
2. Click Add Email Account.
3. Select Gmail as the provider.
4. Click Authorize with Google. You will be redirected to Google's OAuth consent screen.
5. Sign in with the Gmail account you want to connect and review the requested permissions. RapiDesq requests the following OAuth scopes:
   • mail.read — Read incoming email messages and metadata.
   • mail.send — Send replies on behalf of the connected account.
   • Additional scopes for profile identification and Pub/Sub notification setup.
6. Grant the requested permissions. Google issues an access token and a refresh token to RapiDesq.
7. You are redirected back to RapiDesq. The connection now shows as ACTIVE.
8. Configure routing: choose whether incoming emails should be routed to a Team or a Flow (see Routing Configuration below).
9. Save the configuration.

How Gmail real-time sync works

Once connected, RapiDesq establishes a Google Cloud Pub/Sub subscription tied to the Gmail account. When a new email arrives, Google pushes a notification to this subscription in real time. RapiDesq then uses the Gmail API to perform an incremental sync using the account's historyId, which ensures that only new and changed messages are fetched—no redundant downloads, no missed messages.

Connecting Outlook / Microsoft 365

Microsoft connections use Microsoft's OAuth 2.0 flow (via Microsoft Identity Platform) and webhook subscriptions for real-time email delivery.

Step-by-step

1. Navigate to Admin > Channels > Email.
2. Click Add Email Account.
3. Select Outlook / Microsoft 365 as the provider.
4. Click Authorize with Microsoft. You will be redirected to Microsoft's login and consent page.
5. Sign in with your Microsoft account and review the requested permissions. RapiDesq requests scopes including:
   • Mail.Read — Read email messages in the connected mailbox.
   • Mail.Send — Send email on behalf of the connected account.
   • Additional scopes for user profile and webhook subscription management.
6. Grant the permissions. Microsoft issues an access token and a refresh token to RapiDesq.
7. You are redirected back to RapiDesq. The connection shows as ACTIVE.
8. Configure routing: choose Team or Flow routing (see Routing Configuration below).
9. Save the configuration.

How Microsoft real-time sync works

RapiDesq creates a webhook subscription with the Microsoft Graph API, targeting the connected mailbox's mail folder. When a new email arrives, Microsoft sends a notification to RapiDesq's webhook endpoint. The subscription has an expiration date, and RapiDesq automatically renews it before it expires—no manual intervention is required.

Connection Status & Health

Each email connection has a status indicator that reflects the current health of the integration. You can view this on the Admin > Channels > Email page.

Automatic token renewal

OAuth access tokens are short-lived (typically 1 hour). RapiDesq automatically refreshes the access token using the stored refresh token 5 minutes before expiration. This buffer ensures that sync operations are never interrupted by an expired token under normal conditions. The new access token replaces the previous one, encrypted at rest.

Error tracking

RapiDesq tracks the timestamp of the last successful sync (lastSyncAt) and maintains a consecutive error counter. If errors accumulate—for example, repeated API failures or authorization problems—the connection status transitions accordingly. The lastError field records the most recent error message for diagnostic purposes. Once the underlying issue is resolved and a sync succeeds, the error counter resets to zero.

How Emails Become Tickets

Understanding the full lifecycle from inbound email to ticket helps you configure routing, diagnose issues, and set expectations for your team.

The inbound email pipeline

1. Email arrives at the connected inbox (e.g., support@yourcompany.com).
2. Provider pushes a notification to RapiDesq via Google Cloud Pub/Sub (Gmail) or a webhook (Microsoft).
3. RapiDesq fetches the message from the provider's API, retrieving the full content: headers, body (HTML and plain text), and attachments.
4. Contact matching: RapiDesq searches for an existing contact whose email address matches the sender. If no match is found, a new contact is automatically created with the source set to EMAIL.
5. Thread detection: The References and In-Reply-To email headers are inspected. If they match an existing ticket's email thread, the message is appended to that ticket as a new inbound message.
6. New ticket creation: If no existing thread is found, a new ticket is created:
   • The email subject becomes the ticket title.
   • The email body becomes the ticket description.
   • The sender is linked as the ticket's contact.
   • Any attachments are stored and linked to the ticket.
7. Routing: The ticket is routed based on the connection's configuration—either directly to a team queue (TEAM routing) or into a conversation flow for automated triage (FLOW routing).
8. Agent notification: The assigned team or flow handles the ticket from here. Agents see the new ticket in their queue and can respond directly from RapiDesq.

Email Threading

Maintaining conversation threads is essential for keeping context intact across multi-message exchanges. RapiDesq uses standard email headers to track threads reliably.

How it works

Every email contains headers that identify the message and its place in a conversation:

• Message-ID — A unique identifier assigned to each email by the sending mail server.
• In-Reply-To — Contains the Message-ID of the email being replied to.
• References — Contains a list of Message-ID values representing the full chain of the conversation.

When RapiDesq receives an inbound email, it checks the In-Reply-To and References headers against its records. If a match is found, the email is added to the existing ticket as a new message rather than creating a duplicate ticket.

Agent replies preserve the thread

When an agent composes a reply in RapiDesq, the outbound email includes the correct In-Reply-To and References headers. This means the customer sees the response as part of the same email thread in their inbox. When the customer replies again, the headers ensure the message routes back to the same RapiDesq ticket.

When threading breaks

Thread detection depends on the email client preserving these headers. If a customer starts a fresh email (not a reply) about an existing issue, it will create a new ticket because the headers won't reference the original conversation. Agents can manually merge tickets in this scenario.

Routing Configuration

Each email connection is configured with a routing destination that determines how incoming tickets are handled. RapiDesq supports two routing modes: TEAM and FLOW.

TEAM routing

Emails are routed directly to a specific team's ticket queue. Agents on that team see the new tickets and can claim or be assigned them according to the team's normal workflow. This mode is straightforward and works well when:

• You have a small or specialized support team that handles all emails from a given inbox.
• Manual triage is preferred, or the volume is low enough that agents can manage assignment themselves.
• You want tickets to appear immediately in the team's queue with no intermediate processing.

FLOW routing

Emails enter a conversation flow, which processes the ticket through automated steps before it reaches an agent. Conversation flows can perform automated triage—categorizing tickets, setting priority, collecting additional information, or routing to different teams based on conditions. Use FLOW routing when:

• You receive high email volume and need automated categorization or priority assignment.
• Different types of emails should be routed to different teams based on content, sender domain, or other criteria.
• You want to send an automated acknowledgment to the customer before an agent picks up the ticket.
• You need to collect structured data or run conditional logic before routing to a human.

Changing the routing mode

1. Navigate to Admin > Channels > Email and select the connection.
2. Under Routing, choose Team or Flow.
3. Select the target team or the conversation flow from the dropdown.
4. Save the configuration. New emails will use the updated routing immediately; existing tickets are not affected.

Outbound Email & Delivery Tracking

When an agent replies to a ticket that originated from the email channel, the response is sent as an email from the connected inbox back to the customer. This keeps the conversation in a familiar channel for the customer while giving agents the full power of RapiDesq's ticketing interface.

Sending replies

Agents compose replies in the RapiDesq ticket view. The reply is sent using the connected email account's credentials (via the provider API), so the customer receives it from the same address they originally emailed. The outbound message includes the correct threading headers to maintain the conversation thread in the customer's inbox.

Delivery status tracking

Every outbound email message is tracked through a delivery lifecycle:

Delivery status is visible on each outbound message within the ticket timeline. If a message fails or bounces, agents can review the error details and take corrective action—for example, verifying the contact's email address or retrying the send.

Attachments

Agents can attach files to outbound email replies. Attachments are also preserved on inbound emails—when a customer sends an email with attachments, they are stored and linked to the ticket as EmailAttachment records, accessible from the ticket detail view.

Tips & Best Practices

• Use a dedicated support email address. Connect a purpose-built email (e.g., support@yourcompany.com) rather than a personal inbox. This keeps support traffic separate from individual correspondence, makes team transitions seamless, and prevents personal emails from becoming tickets.
• Monitor connection health proactively. Check the email connection status regularly on the Admin > Channels > Email page. A connection that falls into TOKEN_EXPIRED or DISCONNECTED status will silently stop receiving emails. Set up a process to check connection health daily, especially after organizational password resets or security policy changes.
• Use FLOW routing for high-volume inboxes. If an inbox receives dozens or hundreds of emails per day, FLOW routing with a conversation flow enables automated categorization, priority assignment, and conditional routing to different teams—reducing manual triage and improving response times.
• Use TEAM routing for small, focused teams. When a dedicated team handles all emails from an inbox and volume is manageable, TEAM routing is simpler to configure and puts tickets directly into the team's queue with no intermediate steps.
• Reconnect promptly after token expiration. If a connection enters the TOKEN_EXPIRED state, reconnect as soon as possible. While the connection is down, inbound emails accumulate in the inbox but are not synced to RapiDesq. Once reconnected, the incremental sync mechanism will catch up on missed messages.
• Understand threading behavior. Educate your team on how email threading works. If a customer sends a new email about an existing issue (rather than replying to the thread), it will create a new ticket. Agents should be aware of the ticket merge capability for these situations.
• Review bounced and failed messages. Periodically check for outbound messages with FAILED or BOUNCED delivery status. A bounced message means the customer never received your reply. Verify the contact's email address and resend if needed.
• For Microsoft 365 organizations: pre-approve the app. To avoid per-user consent prompts, have your Azure AD administrator grant tenant-wide consent for the RapiDesq application. This streamlines the connection process for anyone on your team who needs to authorize an inbox.