Email Inboxes

An inbox is a dedicated email address that your workspace owns. When someone emails it, the message appears in the inbox view, and — if you've wired one up — a workflow handles the reply automatically. Members on your team can also read and reply by hand. Inboxes work the same way as any other channel: incoming email creates a chat, the assistant follows the workflow's tasks, and humans can take over at any point.

What an inbox is

Each inbox has:

• An email address — either on the platform default domain (free, instant) or on a custom domain you own.
• A default workflow — optional. When set, every incoming email starts an assignment in that workflow.
• A footer — optional text appended to outbound replies (signature, legal disclaimer, support hours).
• Rules — optional filters that decide which emails skip the workflow or get an auto-response.
• Permissions — which member roles can read, send from, or admin the inbox.

A workspace can have as many inboxes as it needs. Most teams use one per audience: support@, billing@, intake@.

Creating an inbox

1. Go to Channels → Inboxes
2. Click Create Inbox
3. Pick a domain (see below) and fill in the slug, name, and default workflow
4. Click Create

Platform default vs custom domain

When you create an inbox, you choose where its email lives.

The platform default appends your workspace slug to keep addresses unique across all customers — support_acme@gravityrail.net and support_globex@gravityrail.net won't collide. With a custom domain, the address is just <slug>@<your-domain>, and slugs need to be unique only within that domain.

To use a custom domain, your org owner first verifies the domain on the org's Domains page by adding the DNS records Gravity Rail provides. Once both ownership and email are verified, the domain shows up in the Domain dropdown when you create or edit an inbox.

Inbox slug rules

The slug is the local part of the address — the bit before the @. A few things to know:

• Use lowercase letters, numbers, and dashes (e.g., support, billing, new-patient-intake). Underscores work but dashes are the convention.
• Slugs must be unique per domain. On the platform default, your workspace slug is appended automatically, so collisions only matter inside your workspace. On a custom domain, slugs must be unique across every workspace in your org sharing that domain.
• Avoid reserved-looking names (postmaster, abuse, admin, noreply) — most email providers treat them specially and inbound mail to them often gets filtered upstream.
• Keep them short and memorable. Customers will type them.

If you try a slug that's already taken, the form returns a clear "address already exists — pick a different slug" error rather than failing later.

Configuration options

Reading and replying

Open Channels → Inboxes and click an inbox to see its emails. Click any email for the full view: sender, recipients, CC, subject, body (HTML and plain text), attachments, and the linked chat if a workflow handled it.

Replying as a member

You can reply to any email by hand:

1. Open the email
2. Click Reply
3. Compose your response (the original is quoted automatically)
4. Click Send

Replies go out from the inbox's address, so the customer sees a single conversation — not a separate thread from your personal email. Threading headers (Message-ID, In-Reply-To, References) are set correctly, so replies stay grouped in the recipient's email client. The inbox's footer is appended automatically.

If the inbox has a workflow attached and the assistant has already replied, your manual reply continues the same chat. The assistant sees what you wrote and uses it as context for any follow-up turns.

How AI processing works

When an inbox has a default workflow:

1. Email arrives at the inbox address
2. Gravity Rail creates an assignment in the workflow
3. A chat is created so the assistant has a place to think
4. The assistant uses its read_email tool to get the full message
5. It generates a reply based on the workflow's task prompts and sends it (unless Auto-Reply is off)

If you turn Assistant Enabled off, incoming mail still lands in the inbox and any rules still run — but no AI processing happens. Use this for inboxes that should be human-only.

Attachments

Both inbound and outbound attachments are supported.

• Each attachment is stored separately and listed below the email body with a download link.
• The total size of one inbound message — body + headers + all attachments combined — must stay under 10 MB. This is the AWS SES limit for inbound mail and Gravity Rail doesn't currently chunk or rewrap larger messages. Senders who exceed it usually receive a bounce from their own provider before the message ever reaches you.
• Outbound replies have the same 10 MB ceiling. Heavy attachments (large PDFs, scans, audio) should be linked from your file storage rather than attached.
• Common malicious file types (executables, scripts) are filtered upstream.

If a sender keeps hitting the size limit, point them at a file-sharing link in your auto-response.

Rules

Rules let you filter or auto-respond to incoming email before the workflow runs.

1. Open the inbox
2. Go to the Rules tab
3. Add a rule with one or more conditions and an action

Conditions

Operators include equals, contains, starts_with, ends_with, matches_regex, greater_than, and less_than.

Actions

Rules are evaluated top-down. The first match wins.

Email security

Inboxes include two security layers that protect you from spam floods and unwanted senders without needing separate tooling: sender rate limiting and allow/deny rules. Both run before the workflow does, so a blocked email never starts an assignment, never uses AI credits, and never fills your inbox.

Sender rate limiting

Rate limiting caps how many emails a single sender can deliver to a workspace in a short window. It stops address-farming scripts, loops between two automated systems, and accidental bulk resends from a newsletter tool set up wrong.

Both limits must pass — a sender hitting either ceiling is rejected until their bucket refills. Limits are per sender per workspace, so alice@acme.com sending to Workspace A has a separate budget from alice@acme.com sending to Workspace B.

A rejected email is dropped silently — the sender's mail server sees a normal SMTP accept, so there's no bounce. The workspace audit log records it with a rate_limited_minute or rate_limited_hour reason if you ever need to investigate.

Customising limits per inbox

If you run an inbox that legitimately receives bursts (form submissions, customer-service queues, integration webhooks-over-email), raise its limits rather than leaving the defaults and manually unblocking senders. Per-inbox overrides are stored on the inbox's rules configuration:

json

Set either or both; whatever you omit falls back to the workspace default. You can also disable rate limiting for an inbox entirely with "rateLimitEnabled": false, but doing this on an internet-facing inbox is almost always a mistake — leave it on and use the allowlist for genuine high-volume senders instead.

Allowlisting trusted senders

Add senders to rateLimitAllowlist so they bypass the limiter without needing a raised ceiling for the whole inbox. Two pattern styles:

json

Matching is case-insensitive. The reason field is for your team's own record — it doesn't affect behavior but helps future-you remember why you trusted a sender months later.

Allow/deny rules

Allow/deny rules filter which senders (or IP addresses) can reach an inbox at all. They run after rate limiting, so a blocked sender never consumes bucket tokens.

Each inbox has an allow mode and a deny mode, independently configurable:

An email is delivered only if it passes the allow check and doesn't match any deny rule. The default is allowMode=all, denyMode=none — accept everyone, reject no one.

Each rule has a field, an operator, and a value:

All sender matches are case-insensitive. CIDR ranges support IPv4 and IPv6. A rule list matches if any rule matches (OR, not AND).

Common patterns

Accept only your own domain:

json

Block a specific spammer:

json

Accept only traffic from your office VPN:

json

Rules are evaluated every time, so you can tighten or loosen without redeploying or waiting for propagation.

Fail-open behavior

All email security checks follow a fail-open design: if the Redis backend that tracks rate-limit counters is unavailable, inbound email is delivered rather than bounced. This prevents an infrastructure blip from silently dropping legitimate mail — the price is that a sustained Redis outage temporarily lifts the rate limit. Gravity Rail monitors the email.rate_limit.events counter (with outcome=fail_open_no_redis or outcome=fail_open_error) internally and will investigate before you notice.

The inbox rules engine (allow/deny) doesn't depend on Redis, so rules continue to filter even when rate limiting is operating in fail-open mode.

When to use what

Member contact preferences and opt-out

Inbound email is always accepted — anyone can write to your inbox. Outbound is gated by the recipient's preferences.

• Per-member opt-out: Every member has an Email notification toggle. When it's off, system notifications and broadcast-style emails skip that member. Workflow replies that the assistant generates in response to a member's own email do still go through, because that's a 1:1 conversation the member started.
• Bouncing addresses: If someone's address starts hard-bouncing, the upstream mail provider's suppression list blocks further sends to it automatically. Repeated bounces from the same domain hurt your sender reputation, so it's worth cleaning these up rather than ignoring them.
• Manual unsubscribes: There's no built-in List-Unsubscribe header on inbox replies today. If you're sending bulk-style email from an inbox (campaigns, broadcasts), include an unsubscribe link in the footer that points at a workflow or page that flips the member's email preference off.

See Notification Preferences for managing per-member channels.

Permissions

Inboxes use role-based permissions. Assign permissions by linking member roles to the inbox in its settings.

A common setup: support team gets Use + Execute, ops leads get Admin, everyone else gets nothing.

Threading

Gravity Rail maintains proper email threading using standard RFC 2822 headers. Replies stay grouped in the recipient's mail client, conversation history is preserved, and the assistant sees the full thread when generating its next reply. You don't need to do anything for this — it's automatic on every reply, manual or AI.

Troubleshooting bounces

When mail to or from your inbox fails to deliver, the bounce usually points at one of these causes:

If a single recipient is stuck on a hard bounce, the upstream mail provider suppresses further sends to that address automatically. Open the email, check the linked chat for the bounce notification, and remove or fix the address on your end.

Common setups

Support inbox

• Workflow: Triage → resolve → follow-up
• Rules: Skip workflow for noreply@* and out-of-office subjects
• Footer: Hours, response-time expectation, link to docs
• Permissions: Support team gets Use + Execute

Sales inquiries

• Workflow: Lead qualification with a calendar booking task
• Rules: Auto-respond with pricing when subject contains "pricing"
• Footer: Calendar link
• Permissions: Sales team gets Use + Execute

Notification-only inbox

• Workflow: None
• Assistant Enabled: Off
• Permissions: Admin-only — used for monitoring, not replies

Tips

• Test with a real send. Email yourself from a personal address and watch the inbox. Did the workflow run? Did the assistant reply? Were headers correct? Five minutes here saves hours of debugging later.
• Set a footer early. Even a one-line "Replies are processed by Gravity Rail's AI assistant — type STOP at any time to reach a human" sets expectations and gives recipients an out.
• Use rules to silence noise. Out-of-office and delivery-failure auto-responses can trigger your workflow if you're not careful. A Skip Workflow rule on common patterns saves credits and clutter.
• Watch the linked chat. When an email triggered a workflow, the email detail view links to the chat. That's where the assistant's reasoning, tool calls, and reply attempts are visible.
• Custom domains take time. DNS propagation isn't instant. Plan domain setup a day before launch, not an hour.

Related

• Channels — Overview of all communication channels
• Email Campaign tutorial — Step-by-step walkthrough of a templated outbound campaign
• Workflows — Building the conversation flows that process emails
• Send Email Action — Sending email from automations
• Notification Preferences — Per-member opt-out toggles
• Template Variables — Using dynamic content in auto-responses