Skip to content

Email Triggers (Outlook/Microsoft 365)

Set up email triggers to automatically process incoming emails and execute workflows based on email content, sender, or other criteria.

What You Can Build

  • Automated ticket creation: Convert support emails into tickets in your system
  • Document processing: Extract data from emails and attachments for processing
  • Lead capture: Automatically process inquiry emails and add to CRM
  • Approval workflows: Route approval requests based on email content
  • Report distribution: Process incoming reports and distribute to stakeholders

Prerequisites

Before setting up email triggers, you will need:

  • A Microsoft 365 (Office 365) organization with Exchange Online
  • An Azure AD application with Graph API permissions
  • Admin access to your Raikoo organization

Setup Steps

Step 1: Create an Azure AD Application

  1. Go to the Azure Portal
  2. Navigate to Azure Active Directory > App registrations
  3. Click New registration
  4. Configure the application:
  5. Name: "Raikoo Email Integration" (or similar)
  6. Supported account types: "Accounts in this organizational directory only"
  7. Redirect URI: Leave blank for now
  8. Click Register
  9. Note the Application (client) ID and Directory (tenant) ID

Step 2: Configure API Permissions

  1. In your app registration, go to API permissions
  2. Click Add a permission
  3. Select Microsoft Graph
  4. Select Application permissions
  5. Add the following permissions:
  6. Mail.Read - To read email messages
  7. Mail.Send - To send email responses (if needed)
  8. User.Read.All - To access user mailboxes
  9. Click Add permissions
  10. Click Grant admin consent (requires Azure AD admin)

Step 3: Create a Client Secret

  1. Go to Certificates & secrets
  2. Click New client secret
  3. Add a description and select an expiration period
  4. Click Add
  5. Important: Copy the secret value immediately - it will not be shown again

Step 4: Create a Connection in Raikoo

  1. Navigate to your organization in Raikoo
  2. Click Connections in the left navigation
  3. Click Create Connection
  4. Configure the connection:
  5. Name: "Outlook Email" (or similar)
  6. Description: Optional description
  7. Platform: Select Graph API (Microsoft)
  8. Go to the Credentials tab
  9. Select Use custom credentials
  10. Enter your credentials:
  11. Tenant ID: Your Azure AD Directory (tenant) ID
  12. Client ID: Your Azure AD Application (client) ID
  13. Client Secret: The secret you created
  14. Default Sender Email: The email address to send from (must be a mailbox in your tenant)
  15. Click Save

Step 5: Create an Email Trigger

  1. Navigate to Integrations in the left navigation
  2. Click Create Trigger
  3. Configure the trigger:
  4. Name: A descriptive name (e.g., "Support Inbox Monitor")
  5. Description: What this trigger does
  6. External Connection: Select the Graph API connection you created
  7. Go to the Execution tab:
  8. Execution Mode: Choose "Chat Agent" for conversational AI responses, or "Workflow" for automated processing
  9. Project: Select the project containing your agent or workflow
  10. Chat Agent (if using Chat mode): Select the AI agent to handle emails
  11. Workflow (if using Workflow mode): Select the workflow to execute
  12. Authentication Mode: Configure how the execution authenticates
  13. Click Save

Step 6: Configure Email Subscription

After creating the trigger, Raikoo automatically sets up a Graph API subscription to monitor the specified mailbox. You should see the trigger's status change to active once the subscription is confirmed.

Execution Modes

Email triggers support two execution modes:

Chat Agent Mode

In Chat Agent mode, incoming emails are sent to an AI agent for conversational processing. The agent receives the email content (including conversation history and attachments) and generates a response, which is sent back as an email reply.

This mode is ideal for:

  • Support inboxes where an AI agent handles customer inquiries
  • Q&A systems that respond to questions sent via email
  • Document analysis where users email attachments for the agent to process

The AI agent sees the full email thread formatted with clear separators between messages, so it can maintain conversation context across multiple exchanges.

Workflow Mode

In Workflow mode, incoming emails trigger a predefined workflow with email content available as parameters. This mode is ideal for structured automation where you need deterministic processing steps.

Email Settings

After creating your trigger, configure email-specific settings in the Email Subscription tab.

Sender Filtering

Control which senders can trigger processing:

Setting Description
Allowed Senders Whitelist of sender patterns. Only emails from matching senders are processed. Supports glob patterns like *@company.com
Blocked Senders Blacklist of sender patterns. Emails from matching senders are ignored. Supports patterns like *@spam.com

If both are configured, the allowed list takes priority - the sender must match an allowed pattern and not match a blocked pattern.

Safety & Loop Prevention

Setting Default Description
Skip auto-replies On Ignores out-of-office replies and auto-generated messages, preventing infinite loops
Skip noreply addresses On Ignores emails from noreply@, no-reply@, and similar addresses
Max email body size (KB) 0 (unlimited) Skips emails with bodies larger than this threshold

Subject Filtering

Setting Description
Required subject patterns Only process emails whose subject matches one of these patterns. Supports glob patterns like [Support]*
Blocked subject patterns Ignore emails whose subject matches. Useful for filtering automated messages like Undeliverable:*

Conversation History

Setting Default Description
History limit 0 (entire thread) Maximum number of previous emails to include for context. The AI sees the full thread formatted with clear separators between messages

Attachments

Email attachment settings control how attachments are processed and presented to the AI:

Setting Default Description
Last message attachments only On Only process attachments from the most recent email in the thread
Convert documents to text On Create readable markdown versions of PDF and Word documents. The AI can read these converted files from its workspace
Send images to AI Off Include image attachments directly in the AI context (requires a vision-capable model)
Send PDFs to AI Off Include PDF files directly in the AI context (requires a compatible provider such as Anthropic)
Send audio to AI Off Include audio files directly in the AI context (requires a compatible provider)
Send video to AI Off Include video files directly in the AI context (requires a compatible provider)
Max attachment size (KB) 5120 (5 MB) Attachments larger than this are skipped. Set to 0 for unlimited
Allowed attachment types Empty (all types) MIME type whitelist. Only attachments matching these types are processed. Example: application/pdf, image/*

How Attachment Processing Works

When the AI agent processes an email with attachments:

  1. Attachments are written to the agent's workspace as files (e.g., /report.pdf, /screenshot.png)
  2. Document conversion (if enabled) creates shadow markdown files alongside the originals (e.g., /report.pdf.md) so the agent can read their content
  3. Context-stuffing (the "Send to AI" options) additionally includes the file data directly in the AI's input context, allowing models that support native file handling to process them directly
  4. The AI agent is informed about which files are available in its workspace

The workspace approach means the agent can reference attachments by path and use tools to read or process them, even if they are not directly context-stuffed.

Reply Behavior

Setting Default Description
Reply All Selected Include all original recipients (To and CC) in the response
Reply - Send only to the original sender

Email Parameters Available in Workflows

When an email triggers a workflow, the following parameters are available:

Parameter Description Example
TRIGGER_EMAIL_FROM Sender's email address customer@example.com
TRIGGER_EMAIL_FROM_NAME Sender's display name John Smith
TRIGGER_EMAIL_SUBJECT Email subject line Help with my order
TRIGGER_EMAIL_BODY_TEXT Plain text body I need help with...
TRIGGER_EMAIL_BODY_HTML HTML body content <p>I need help with...</p>
TRIGGER_EMAIL_RECEIVED_AT Timestamp when received 2024-01-15T10:30:00Z
TRIGGER_EMAIL_HAS_ATTACHMENTS Whether email has attachments true or false
TRIGGER_EMAIL_MESSAGE_ID Unique message identifier AAMkAGI2...

Example Workflow

Here is an example of how to process incoming support emails:

  1. Start - Triggered by incoming email
  2. AI Operation - Analyze email content to determine category
  3. Uses TRIGGER_EMAIL_SUBJECT and TRIGGER_EMAIL_BODY_TEXT as input
  4. Outputs: category, priority, summary
  5. Conditional Branch - Route based on category
  6. Create Ticket - Use Execute JavaScript to create a ticket in your system
  7. Send Confirmation - Use Send Email operation to confirm receipt

Sending Emails

In addition to triggering workflows on incoming emails, you can send outbound emails from workflows and AI agents using the Send Email operation.

Using Send Email in Workflows

  1. Add a Send Email operation to your workflow
  2. Select your Graph API connection
  3. Configure the email:
Field Description Example
To Recipient email addresses (comma-separated) user@example.com, team@example.com
Subject Email subject line Your request has been processed
Body Email content Hello, your request...
Body Format Choose "text" or "html" html
CC Carbon copy recipients (optional) manager@example.com
BCC Blind carbon copy recipients (optional) archive@example.com

HTML Email Formatting

When using HTML format, you can include rich formatting:

<h1>Request Processed</h1>
<p>Hello <strong>{{WorkflowParameters.TRIGGER_EMAIL_FROM}}</strong>,</p>
<p>Your request has been processed successfully.</p>
<ul>
  <li>Request ID: {{WorkflowParameters.requestId}}</li>
  <li>Status: Completed</li>
</ul>
<p>Best regards,<br>Support Team</p>

Using Send Email from AI Agents

AI agents can send emails using the send_email tool:

I'll send a confirmation email to the customer.

Using send_email:
- to: customer@example.com
- subject: Your order confirmation
- body: Thank you for your order...
- bodyFormat: html

Replying to Trigger Emails

When a workflow is triggered by an incoming email, you can easily reply to the sender:

  1. Add a Send Email operation
  2. Use {{WorkflowParameters.TRIGGER_EMAIL_FROM}} as the To address
  3. Use Re: {{WorkflowParameters.TRIGGER_EMAIL_SUBJECT}} as the Subject
  4. Compose your response body

Common Use Cases

  • Automated acknowledgements: Confirm receipt of support requests
  • Report delivery: Send generated reports to stakeholders
  • Notification emails: Alert team members about important events
  • Customer communications: Send updates about order status
  • Workflow results: Email the output of AI processing

Email Sender Requirements

The email is sent from the Default Sender Email configured in your Graph API connection. This email address must:

  • Be a valid mailbox in your Microsoft 365 tenant
  • Have the appropriate send permissions for the Azure AD app
  • Be a licensed user or shared mailbox

Troubleshooting

Subscription Not Activating

  1. Verify your Azure AD app has the correct permissions granted
  2. Check that admin consent was provided for the permissions
  3. Ensure the client secret has not expired
  4. Verify the mailbox exists and is accessible

Emails Not Triggering Workflows

  1. Check that the trigger is set to Active
  2. Verify the mailbox being monitored is correct
  3. Check for any errors in the Raikoo logs
  4. Ensure the Graph API subscription is active (Raikoo automatically renews)

Permission Errors

  1. Verify the Application permissions (not Delegated)
  2. Confirm admin consent was granted
  3. Check that the app has access to the specific mailbox

Delayed Email Processing

  1. Graph API notifications can have slight delays (typically under 30 seconds)
  2. Complex workflows may take additional time to process
  3. Monitor workflow execution logs for bottlenecks

Subscription Management

Raikoo automatically manages Graph API subscriptions:

  • Creation: Subscriptions are created when you save an email trigger
  • Renewal: Subscriptions are automatically renewed before they expire (3-day maximum)
  • Deletion: Subscriptions are removed when you delete the trigger

Security Considerations

  • Least privilege: Only request the Graph API permissions you need
  • Secret rotation: Regularly rotate your Azure AD client secrets
  • Mailbox access: Consider using a dedicated mailbox for integration
  • Audit logging: Azure AD logs all Graph API access for compliance

Best Practices

  • Use dedicated mailboxes: Create mailboxes specifically for automated processing
  • Filter carefully: Configure your trigger to only process relevant emails
  • Handle edge cases: Account for emails with missing fields or unexpected formats
  • Monitor quotas: Be aware of Microsoft Graph API rate limits
  • Test thoroughly: Test with various email formats before production use

Next Steps