Inbox

The Inbox is a unified message hub. Instead of checking email, Slack, WhatsApp, and other channels separately, you can push all incoming messages into SupaNet and manage them in one place.

Why the inbox is useful

The inbox lets you:

• Collect messages from any source — email, Slack, WhatsApp, SMS, webhooks, or manual entries.
• Keep them organized — mark as read, file messages into collections, or add notes.
• Chat about them — include a collection of messages in Chat to have the assistant help with or summarize them.
• Automate on them — set up a listener (automation rule) to react when a new message arrives.
• Share with your team — mark a message as workspace-visible so everyone can see it and file it into shared collections.

Where to find your inbox

On the top navigation bar, select Inbox. You'll see all your messages in a list, organized by source. Click a message to read its full body and optionally add notes.

Creating a message

Click New message to compose and send a message directly into your inbox. You can set:

• From — who it's from (your name, an email, or a handle).
• Subject (optional) — a title or summary.
• Body (required) — the message content.
• Visibility — private (only you) or workspace (the whole team can see it).

When you send, the message lands in your inbox immediately.

Receiving messages from external sources

You can receive messages in your inbox from multiple sources — IMAP email accounts, email providers, Slack, WhatsApp, your own scripts, or integrations like Zapier.

Email via IMAP (pull your own mailbox)

You can connect an IMAP mailbox to SupaNet and have the workspace automatically poll it for new messages. This is useful for monitoring mailboxes without relying on an email provider's push API.

To add an IMAP inbox:

1. Go to Inbox → Inboxes (top-right button).
2. Click Add inbox and select a provider (Gmail, Outlook, Yahoo, iCloud, Fastmail, or enter custom settings).
3. Enter your mailbox username (usually your full email address) and an app password — not your login password.
4. Choose how often to check for new mail (1–1440 minutes; default 5 minutes).
5. Decide if the inbox is private (only you see mail) or workspace (your team can see and file it).

The workspace automatically polls your mailbox every minute, checking only accounts that are due (respecting their individual check intervals). New messages land in your inbox with source='email' and immediately fire a message.received event, so you can set up listeners to route them just like webhooks.

Important: Use an app-specific password, not your real login password. Almost every mail provider requires an app password once 2FA is enabled.

• Gmail/Google Workspace: Google Account → Security → App passwords (generate for "Mail")
• Outlook/Microsoft 365: Account Security → App passwords
• Yahoo: Account Security → Generate app password
• iCloud: appleid.apple.com → App-Specific Passwords
• Other providers: Check your provider's security settings

Inbox options

When editing an inbox, you can toggle:

• Active (polling on) — whether the workspace polls this mailbox for new mail.
• Mark messages read on the server after importing — by default, the poller marks each ingested message as \Seen on the IMAP server, so your mailbox reflects what's been pulled. Untick this to leave the folder untouched.

Testing and re-scanning

Before saving a new inbox or after changing its settings:

• Click Test connection to verify the mailbox credentials and see how many messages are in the folder. This proves login and folder access work before you save.
• Click Test message to insert a synthetic test email that fires a message.received event. This lets you verify that your listeners and automations trigger correctly without waiting for real mail to arrive.

If connection fails (e.g., firewall blocking port 993), the error shows on your inbox card; other mailboxes aren't affected.

If you need to re-import mail (e.g. after a config change or to recover messages already in the folder), click Re-scan — this resets the ingest cursor so the next poll re-imports the most recent mail.

Routing new mail

The inbox editor also has a "When new mail arrives here" section that lets you automatically route incoming messages to a destination while they still land in your inbox:

• Just add it to the Inbox — no routing (default).
• Also save it to a table (map fields to columns) — each message deterministically populates a row in one of your tables. Map message fields (sender, subject, body, received date) to columns using dot-path tokens like {{event.data.subject}} and {{event.data.from_address}}. No model is involved, so this is purely deterministic — the same as a webhook's direct-table mode.
• Also save it to a table (whole message as JSON in one column) — stores the entire message as a JSON object in a single column. Choose a table and a JSON-type column; the whole message will be saved there with all its fields intact. This is simpler than mapping individual fields and keeps the full message structure for later processing.
• Also run an agent — the agent receives the message as context and can process it however its instructions say.
• Also run a function — invoke a custom tool directly on the message data.

The routing runs through the same automation dispatcher as every other listener, so it appears on the Listeners page (editable there, too). You can disable routing by selecting "Just add it to the Inbox" again.

Email via provider inbound-parse (push)

If you have email set up in your workspace with an email provider (Postmark, Resend, etc.), incoming emails automatically appear in the inbox with source='email'. See Email to configure inbound email.

Anything else (Slack, WhatsApp, scripts, Zapier)

Use the public message-inbound API to push a message:

curl -X POST 'https://<project-ref>.supabase.co/functions/v1/message-inbound' \
  -H 'Authorization: Bearer <connect-claude-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "slack",
    "from": "Jane <jane@example.com>",
    "subject": "deploy finished",
    "body": "prod is green",
    "url": "https://slack.com/archives/...",
    "external_id": "slack-msg-123"
  }'

You authenticate using a personal connection token (from Settings → Connect Claude or the API page) or a Supabase session JWT. Only body is required; include external_id if your source might re-deliver the same message (it dedupes).

The assistant and agents can also save messages using the save_message builtin.

Reading and managing messages

On the Inbox page:

• Click a message to open it in detail, read its full body, add notes, or mark it read/unread.
• Filter by source — click a source chip (Email, Slack, etc.) to show only messages from that source.
• Mark as read/unread — track which messages you've seen.
• Delete — remove a message from your inbox.

Collections and chat context

You can file messages into collections — the same named groups you use for artifacts, files, and to-dos. Multi-select messages and click Add to collection to file them. When you use a collection in Chat (via the 📚 picker), the assistant has access to the messages alongside artifacts, files, and tasks.

This is useful when you want to chat with a team about a set of messages — e.g., "summarize all these customer emails" or "help me reply to these support requests."

Sharing and collaboration

• Private messages — only you (and admins) can see or edit them.
• Workspace messages — everyone on your team can see them, file them into collections, and add notes.

When a message is workspace-visible, your team sees it immediately.

Automating on incoming messages

When a message arrives in your inbox, it emits an event that can trigger an automation rule (a listener). For example:

• "When a WhatsApp message arrives in the Support collection, run the Triage agent"
• "When an email from a specific domain arrives, file it into the Leads collection"

See Automation & Listeners for how to set up these rules.