Integrate Workflon into a Mail App

Overview

This guide shows how to integrate Workflon — your AI product copilot — into a mail application. You will:

• Create an organization and an app, and get your public API key.
• Embed the widget script in your client.
• Define actions like sendEmail, archiveEmail, markAsSpam, deleteEmail.
• Provide user context (emails, contacts) to ground the copilot.
• Test end-to-end, and follow best practices for production.

If you want to see it in action first, try the demo at /mail-demo.

Prerequisites

• An Workflon account and access to the dashboard
• One organization with at least one app created
• The app’s active API key (public key)
• A client app where you can include a script tag (React example shown, but any web app works)

1) Create Org and App, Get Public Key

1. Go to /dashboard and select or create an organization.
2. Use the App switcher to create/select an app.
3. Go to Billing if you need higher limits; otherwise Free plan is fine to start.
4. Generate an API key for your app and copy the Public Key (starts with pk_).

2) Include the Workflon Script

Add the script to your app’s HTML (or load it dynamically once you have the public key):

<!-- Replace YOUR_PUBLIC_KEY -->
<script src="/api/script/YOUR_PUBLIC_KEY" async></script>

In React, you can dynamically inject it after mount:

useEffect(() => {
  const pk = process.env.NEXT_PUBLIC_WORKFLON_PUBLIC_KEY;
  if (!pk) return;
  const id = "-script";
  if (!document.getElementById(id)) {
    const s = document.createElement("script");
    s.id = id;
    s.async = true;
    s.src = `/api/script/${pk}`;
    document.body.appendChild(s);
  }
}, []);

3) Register Mail Actions

Expose the actions your copilot can perform. The copilot will call these handlers with structured parameters extracted from user prompts.

declare global {
  interface Window {
    Workflon?: {
      setActions: (
        actions: Record<string, (params: any) => Promise<any>>,
      ) => void;
      setUserContext: (ctx: Record<string, any[]>) => void;
      show: () => void;
    };
  }
}
 
window.Workflon?.setActions({
  sendEmail: async ({ to, subject, body }) => {
    // Validate recipient, send via your mail API, persist, update UI
    return `Sent email to ${to} with subject "${subject}".`;
  },
  archiveEmail: async ({ emailId }) => {
    // Update storage and UI
    return `Archived email ${emailId}.`;
  },
  markAsSpam: async ({ emailId }) => {
    return `Marked email ${emailId} as spam.`;
  },
  deleteEmail: async ({ emailId }) => {
    return `Deleted email ${emailId}.`;
  },
});

Tips:

• Return concise confirmations for great UX.
• Throw errors with helpful messages to guide users.
• Keep action names verb-first and domain-specific (sendEmail, archiveEmail, …).

4) Provide User Context

Ground the copilot with relevant, up-to-date context (emails, contacts, folders). This improves accuracy and reduces follow-up questions.

window.Workflon?.setUserContext({
  emails: emails.map(({ id, subject, fromName, to, status }) => ({
    id,
    subject,
    from: fromName,
    to,
    folder: status,
  })),
  contacts, // e.g. [{ id, name, email }]
});

Best practices:

• Keep context compact; prefer IDs and key fields over full bodies.
• Update context after actions so the assistant reflects the latest state.
• Avoid sensitive content unless necessary; prefer derived summaries.

5) Launch and Test

• Trigger the copilot via your UI (e.g., a button) or call window.Workflon?.show().
• Try prompts like:
  • “Send Bob a status update about Project Phoenix.”
  • “Archive yesterday’s newsletter.”
  • “Mark Alice’s email as spam.”

6) Production Considerations

• AuthZ: Validate that users can act on the specified resource (emailId, contact).
• Idempotency: Avoid duplicate sends on retries; use request IDs.
• Observability: Log action executions and failures; pipe to your telemetry.
• Limits: Watch monthly request limits per organization in /dashboard.
• Privacy: Avoid sending PII in context where not needed.

Full Example (Mail Demo)

Our /mail-demo contains a working integration: script loading, actions, and context setup. Use it as a blueprint and adapt it to your data model and API.

Troubleshooting

• The copilot isn’t visible: ensure the script is loaded with a valid public key.
• Actions not called: confirm window.Workflon.setActions runs after the script loads.
• Wrong data: verify setUserContext values and refresh after each action.