Use Case Provider

Practical Use Case: Unipile Provider¶

The Unipile Provider is a really good example of a powerful and practical extension of the MindFlight AI MFO Server. It is designed to handle email workflows, private messaging on social networks, linkedin API, calendar workflows. In our case study, Unpile makes it possible to synchronize, process, and respond to emails automatically.

What does Unipile Email Provider ?¶

Unipile as a Provider in this use case acts as a bridge between your email accounts and the MindFlight server.

It takes care of:

• Synchronizing emails in the background.
• Handling incoming email notifications via webhooks.
• Exposing API endpoints to list, tag, draft, send, and process emails.

Metaphor:
Think of Unipile as your AI mailroom assistant: it fetches new letters, sorts them, alerts the server when something new arrives, and helps draft replies automatically.

Core Features for Unipile Email Provider¶

Behind the Scenes¶

1️⃣ Sync Jobs¶

The Unipile Provider registers a background job that runs at intervals to sync emails. This ensures the server always has the latest data.

Example:
- Every 5 minutes, the job checks Unipile for new emails and updates the database.

2️⃣ Webhook Handling¶

When a new email arrives, Unipile sends a message to the webhook to MFO. This is handled by the email_webhook_handler.go file.

Flow:

1. Unipile → sends a message through the webhook (JSON payload about the new email).
2. The MFO Client → receives the webhook on the route /webhooks/unipile/notify.
3. The webhook handler → validates and parses the email data.
4. The MFO Client → publishes an internal event unipile.email.received.

3️⃣ API Exposure¶

The Unipile Provider registers its tools so you can:

• List emails in your inbox.
• Send a new email.
• Process emails (e.g., mark as read, archive).

Example API Tool: unipile_list_emails
You can call this via the /api/tools/unipile_list_emails endpoint to fetch recent messages.

Internal Events¶

One of the strengths of MFO Client is how it triggers internal workflows using events.

This event allows you to chain custom workflows. For example, when unipile.email.received is triggered, the MFO server might automatically:

• Start an AI process to draft a reply.
• Save the email content to a database.
• Notify a human operator if manual review is needed.

How Unipile Registers Its Schema ?¶

When the server starts, the Unipile Provider registers:

• Its schema (what tools it offers).
• Its routes (for handling webhooks).
• Its jobs (for sync).

This happens via the Init() function in the Unipile provider code, which tells the server:

• What tools are available (e.g., list emails, send email).
• Which routes to expose (e.g., /webhooks/unipile/notify).
• What jobs to schedule (e.g., email sync every X minutes).

Metaphor:
It's like the provider checks into the server and says: "Here's my toolbox, here's where to send me notifications, and here's what I'll do in the background."

Example Workflow: New Email Ingestion¶

Let's see what happens step by step when a new email arrives.

1️⃣ 📬 Email Received:
A new email lands in your inbox (e.g., via Gmail).

2️⃣ 🚀 Webhook Sent:
Unipile sends a notification's webhook to your MindFlight server.

3️⃣ 🛂 Webhook Processed:
The server's webhook route /webhooks/unipile/notify receives and MFO Client validates the email data.

4️⃣ 🔔 Event Triggered:
The MFO Client fires the unipile.email.received event.

5️⃣ 🤖 Workflow Activated:
A background job starts to process the email (for example, drafting a reply).

6️⃣ 📡 Notification Sent:
If you have subscribed to email.processed notifications, your app gets a webhook saying the email has been handled.

Mermaid Diagram: Email Ingestion Flow¶

sequenceDiagram
    participant EmailService as Email Service (Gmail, etc.)
    participant Unipile as Unipile Provider
    participant Server as MindFlight AI Server
    participant Client as Client App

    EmailService->>Unipile: New email arrives
    Unipile->>Server: Send webhook (/webhooks/unipile/notify)
    Server->>Server: Process webhook & validate
    Server->>Server: Fire event (unipile.email.received)
    Server->>Server: Start job (e.g., draft reply)
    Server->>Client: Notify via webhook (email.processed)

Quick Recap¶