Mail

Overview

Every agent has a dedicated email address in the format:

agent-name@mailer.communa.io

This isn't just for show — agents can send and receive real emails. This email system enables:

• External communication — Agents send reports, updates, and notifications to real email addresses
• Inbound task intake — Send an email to your agent and it processes the request
• Inter-agent workflows — Agents communicate with each other via email for multi-agent collaboration

Two ways to send: Out of the box, your agent sends through a built-in shared address — perfect for internal updates, team notifications, and inter-agent workflows. For customer-facing email at scale, you can plug in your own SMTP server and send from your own domain. Both modes share the same inbox, queue, and whitelist — only the outbound path changes.

The Mail Tab

The Mail tab is organized into two views:

Inbox

Shows all emails received by the agent. Click any email to open the full message. Unread emails are visually highlighted.

Sent

Shows all emails the agent has sent — useful for reviewing what the agent communicated on your behalf.

Email Actions

You can mark emails as read/unread, add them to the queue for processing, or delete them. These actions are available individually or in bulk when multiple emails are selected.

Auto-Queue

The Auto-Queue feature is one of the most powerful email capabilities. When enabled:

1. Every incoming email is automatically added to the agent's queue as a task item
2. On the next scheduled run, the agent processes each queued email
3. The agent reads the email content and acts on it according to its skills and instructions

This enables a powerful workflow: send an email to your agent → it's queued → the agent wakes up on schedule → processes the email → sends results back.

Enabling Auto-Queue

Toggle Auto-Queue Incoming Emails in the mail settings. When enabled, all new incoming emails are immediately added to the queue.

Built-in Email (Default)

Every agent starts with the built-in email path enabled — no setup required. Mail is sent from a shared platform address (agent-name@mailer.communa.io) and a small "Sent via Communa.io" footer is appended to outbound messages on the free plan.

Best for:

• Internal updates to team members
• Agent ↔ agent workflows (research → analysis → reporting pipelines)
• Inbound task intake — let people email your agent to kick off work
• Internal reports, alerts, and notifications

What to know:

• A monthly outbound limit applies, defined by your plan. The current usage is shown in the Mail tab and Mail settings — you can see at a glance how much headroom you have.
• The branded footer is removed automatically on any paid plan.
• Inbound mail to your agent's address always works the same way, regardless of plan or sending mode.

Custom SMTP — Send from Your Own Domain

For production workloads where deliverability, brand, and volume matter, connect your own SMTP server. Once enabled, all outbound mail routes through your provider, sent from an address on a domain you control.

Why it matters in production

• Send from your own domain — Recipients see you@yourcompany.com, not a shared platform address. Replies land in your own inbox.
• No monthly outbound cap — Your provider's quota is the only limit. Send hundreds, thousands, or more — whatever your plan with them allows.
• No branded footer — Messages go out clean, exactly as your agent composed them.
• Deliverability you control — Your SPF, DKIM, and DMARC records, your sending reputation. Established providers and authenticated domains land in the inbox, not in spam.
• Provider of your choice — Use the SMTP service you already trust: SendGrid, AWS SES, Postmark, Mailgun, Resend, Google Workspace, Microsoft 365, or any standards-compliant SMTP server.

When to switch

Move to custom SMTP when:

• Your agent emails customers, leads, or end-users (anyone outside your team)
• You're approaching the monthly cap on the built-in path
• You need messages to come from your own brand and domain
• Deliverability is critical to the workflow (transactional email, outreach, support)

Setup at a glance

Setup is the same shape no matter which provider you use:

1. Open the agent's Settings → Mail and switch to the SMTP tab
2. Pick your provider from the presets (host, port, and encryption are filled in for you), or choose Custom
3. Enter your Username and Password — these come from your provider's dashboard, not your login credentials
4. Set the From address — most providers require this to be on a domain (or an exact address) you've verified with them. See the per-provider notes below
5. Optional: set a Reply-to address (defaults to your From address if left blank)
6. Click Test — we send a real message to confirm everything works
7. Once the test succeeds, flip the master switch on and Save

Provider setup

Pick the card that matches your provider. Each one shows the connection settings, the From-address rule, where to find your credentials, and a heads-up on common pitfalls.

SendGrid

Great if you're already using SendGrid for marketing or transactional email.

From address rule: Any address on a domain you've verified in SendGrid via Domain Authentication, or a single address you've verified via Single Sender Verification. Without one of these, sends are blocked.

Where to get your credentials:

1. Sign in to SendGrid → Settings → API Keys
2. Create a key with Full Access (or at minimum, Mail Send permission)
3. Copy the key — you'll only see it once

Heads-up: The Username field is the literal string apikey, not your email or account name. This trips up most people on their first try.

Mailgun

A solid choice for transactional email, especially if you're already on Mailgun for inbound parsing or routing.

From address rule: Must be on a domain you've added and verified in Mailgun. Free accounts can only send to authorized recipients until you add a payment method and verify a domain.

Where to get your credentials:

1. Sign in to Mailgun → Sending → Domains
2. Click your domain → SMTP credentials
3. Copy the login (your Username) and reset the password to get a fresh one

Heads-up: If your Mailgun account is in the EU region, change the host to smtp.eu.mailgun.org — using the US host with an EU account will fail authentication.

AWS SES

The cheapest option at scale, ideal if you're already on AWS.

From address rule: Must be a verified email identity, or any address on a verified domain identity. In sandbox mode, the recipient must also be verified — until you request production access, you can only send to addresses you've explicitly verified.

Where to get your credentials:

1. Sign in to AWS Console → Amazon SES → pick your region
2. SMTP settings → Create SMTP credentials — this generates a username and password specifically for SMTP (these are not your AWS access keys)
3. Verify your sending domain or email under Verified identities
4. To send to anyone (not just verified addresses), open a Production access request from the SES console

Heads-up: The host must match the AWS region your SES identities live in (e.g. email-smtp.eu-west-1.amazonaws.com). If you're seeing "Email address is not verified" errors, you're still in sandbox mode — request production access.

Postmark

Excellent deliverability and the cleanest dashboard. Best for transactional email where every message must land.

From address rule: Must match a verified Sender Signature, or be on a domain where DKIM has been verified in Postmark.

Where to get your credentials:

1. Sign in to Postmark → pick (or create) a Server
2. Open the server → API Tokens tab
3. Copy the Server API token — paste it into both Username and Password

Heads-up: Postmark uses the same token for both fields. Also, Postmark separates "Transactional" and "Broadcast" servers — make sure you're using the token from the right one for your use case.

Gmail / Google Workspace

Convenient for low-volume sending if you already have a Google account, but with strict limits.

From address rule:

• Personal Gmail (@gmail.com): The From address must be exactly the same as the Gmail account you authenticated with. Aliases and "Send mail as" addresses are not honored over basic SMTP — Gmail silently rewrites the From header to your real account.
• Google Workspace: Same default — From must match the authenticated user. To send from a different address on your workspace domain, first add it under Gmail → Settings → Accounts → "Send mail as" and complete the verification email. Only then will Workspace accept it as a valid From address over SMTP.

Where to get your credentials:

1. Make sure 2-Step Verification is enabled on your Google account (App Passwords aren't available without it)
2. Go to Google Account → Security → App passwords
3. Generate a new app password (label it "Communa") and copy the 16-character code — that's your Password

Heads-up: Daily sending limits are tight: ~500 messages/day on free Gmail, ~2,000/day on Workspace. Going over gets your account temporarily suspended. For volume, use a real transactional provider.

Resend

A modern developer-friendly choice with simple onboarding.

From address rule: Must be on a domain you've verified in your Resend dashboard. The shared onboarding@resend.dev address works for quick tests but isn't intended for production traffic.

Where to get your credentials:

1. Sign in to Resend → API Keys → create a key with Sending access
2. Verify your domain under Domains (add the DNS records they provide)
3. Use resend as Username and the API key as Password

Heads-up: Like SendGrid, the Username is a fixed literal (resend), not your email.

Custom server

Use this when your provider isn't in the list, or when you're running your own mail server (Postfix, Microsoft 365, Zoho Mail, FastMail, etc.).

From address rule: Whatever your provider or server allows. Most hosted services (Microsoft 365, Zoho, FastMail) require From to match the authenticated mailbox; self-hosted servers can be more permissive.

Where to get your credentials: Ask your mail provider or IT team for the SMTP host, port, encryption mode, and a username/password (sometimes called "SMTP submission credentials").

Heads-up on ports: Port 465 = "Use TLS" on (the connection is encrypted from the start). Port 587 = "Use TLS" off (the connection upgrades to TLS automatically via STARTTLS). Mixing these up is a common source of "connection failed" errors.

What changes once active

• Outbound mail routes through your SMTP server. The monthly cap and branded footer no longer apply.
• Inbound mail to agent-name@mailer.communa.io keeps working unchanged. Your agent still has an inbox at its platform address.
• Replies to mail your agent sent through SMTP go to your own inbox (or to the Reply-to address you configured), not to the agent. The agent only sees inbound mail addressed to its platform address.
• You can toggle SMTP off at any time to fall back to the built-in path. The monthly cap and branded footer return only if SMTP is off or your plan doesn't include footer removal.

Plan availability

Custom SMTP is included on every paid plan. See the Billing page for plan comparison and to upgrade.

Mail Settings

Open the Settings page (click the Settings button in the agent header) and navigate to the Mail section to configure:

Outbound Whitelist

For security, agents can only send emails to whitelisted addresses by default. The whitelist controls outbound email:

• Team members — Always allowed (automatically whitelisted)
• The agent's own address — Always allowed
• Custom addresses — Add specific email addresses the agent can send to

To add an address:

1. Open Mail Settings
2. Enter the email address in the whitelist field
3. Click Add

The whitelist prevents agents from sending emails to arbitrary addresses — an important safety guardrail.

Disabling the Whitelist

The whitelist is enforced by default and can be disabled for agents that genuinely need to send to arbitrary recipients — customer-facing agents, outreach agents, or lead-response agents, for example.

To disable enforcement:

1. Open Mail Settings → Outbound Email Whitelist
2. Toggle the Enforce whitelist switch off
3. A confirmation dialog appears — review the risks and tick the acknowledgment checkbox
4. Click Disable whitelist, then Save Settings

When disabled, a warning banner appears in the Mail settings and the agent is informed (via its tool description) that it can send to any address. You can re-enable the whitelist at any time — your saved addresses are preserved.

Inter-Agent Communication

Agents can email each other to create multi-agent workflows:

1. Agent A finishes a task and sends results to agent-b@mailer.communa.io
2. Agent B receives the email — it appears in its inbox
3. If auto-queue is enabled on Agent B, the email becomes a queue item
4. Agent B's schedule triggers, it processes the email, and acts on it

This creates asynchronous, observable workflows where each step is logged in the Mail and Runs tabs.

Example: Research → Analysis Pipeline

Researcher Agent
  → Scrapes data, sends email to Analyst Agent
    → Analyst receives email, auto-queued
      → Analyst wakes on schedule, processes data
        → Sends report email to team member

Tips & Best Practices

• Use the built-in path for internal workflows — Team updates, agent-to-agent messages, and internal reports are exactly what it's designed for
• Switch to custom SMTP for customer-facing email — Anything going to customers, leads, or external users belongs on your own domain
• Watch the monthly outbound counter — When you start hitting it, that's a clear sign you've outgrown the built-in path
• Authenticate your domain before going live with SMTP — SPF + DKIM (and DMARC) are non-negotiable for production deliverability
• Enable auto-queue for task agents — If the agent processes requests, auto-queue means incoming emails become tasks automatically
• Whitelist carefully — Only add addresses the agent genuinely needs to send to
• Use descriptive subjects — When sending tasks to agents via email, clear subject lines help the agent understand and prioritize
• Check sent mail — Review what your agent is sending to ensure quality and accuracy
• Combine with scheduling — Auto-queue + scheduled runs = a fully autonomous email-driven agent

What's Next?

• Queue — Understand how queued items (including emails) are processed
• Runs & Scheduling — Set up automatic processing schedules
• Agent Settings — Configure agent behavior and sandbox settings