# Inbox setup, messaging and follow-up recovery

## What this contract covers

The OpenAPI contract covers seven capabilities implemented by the trusted Home-to-Agents gateway: scoped conversation reads, reply draft/create/read/send, automatic follow-up read/result recording, and non-executable automation proposals. It excludes operator-console routing, channel credentials, contact-permission overrides, raw flow internals, Groovy decision queues and CRM execution. The email outreach guide below describes the signed-in Automations workflow; it does not add an outreach capability to that gateway or Home's delegated read tools.

## Reply sequence

1. Read a conversation with `inbox.conversations.read` under the current Home actor and exact tenant/project.
2. Create one immutable draft with `inbox.reply.draft` and a stable idempotency key. A key replay with the same body returns the existing draft; different input conflicts.
3. Present the saved channel, recipient, body, takeover requirement and expiration to the user.
4. After explicit confirmation, send only by `draft_id` using `inbox.message.send`. Recipient/body override fields do not exist.
5. If the result is lost, use `inbox.reply.read`. A recorded message ID proves the Inbox queue receipt; it does not prove downstream provider delivery or customer receipt.

## Follow-up sequence

`inbox.followups.read` exposes bounded automatic work for active Inbox policies in one project. An executor performs the approved work through its appropriate reviewed tools, then `inbox.followups.complete` records `in_progress`, `completed` or `error`. Keep the idempotency key stable for that logical result and increase the attempt only for a genuinely new attempt. This capability does not send messages and cannot create or activate a policy.

## Automation proposal sequence

`inbox.automation.draft` accepts a reviewable audience, objective, preferred channels, stop conditions, assumptions and missing requirements. It stores an immutable draft and returns a review path. It cannot compile criteria into executable queries, choose a sender, establish consent, publish routing or activate a flow. Those remain explicit project-admin review steps.

## Evidence and errors

Every gateway response carries the invocation ID and a tenant/project/capability receipt. Home and Agents use that ID as a content-free log correlation reference; it is not an outcome receipt, a cross-product trace query grant or proof of provider delivery. A receipt says the gateway operation completed; interpret its data according to the capability. Protected writes may return `intelligence_action_awaiting_approval`; review the redacted action in Home Activity and resume the exact same invocation only after approval. A retryable error is permission to inspect and reconcile, not permission to repeat a write automatically. `409` means state or safety evidence changed. `503` means required context is unavailable; neither status proves that nothing happened downstream.

## CRM contacts and calls

Click the person's name in Inbox to open their contact. The project's CRM owns the name, phone, email, role, notes and custom fields. Find an existing person or create one, then explicitly link it to this conversation. Datagran CRM supports editing inside Inbox and in its own People list or person card. Salesforce supports searching and linking existing Contacts or Leads, editing permitted standard and primitive custom fields, and refreshing phones for calls. Create Salesforce records in Salesforce first. Titan supports linking by customer ID and refreshing contact details; its current API cannot edit existing phone/email fields. Hibe needs a human contact-editing API extension; its voice customer-verification tools are not used for contact edits.

With no accessible CRM connection, the contact card offers Enable Datagran CRM first and Connect another CRM second, preserving tenant and project. A workspace administrator handles enablement and grants. Administrators explicitly assign the connection to Inbox with crm.read and crm.write; newly advertised capabilities do not widen existing assignments. Reads require current Inbox project access and CRM read permission; changes require operator access and a CRM write grant on the selected connection. No independent Inbox address book or browser-held CRM credential is created.

Phone numbers include the country code. Save keeps alternate contact points and structured custom fields. A stale edit returns a conflict instead of replacing newer work. An uncertain creation can be recovered without duplicating the person. Open full CRM record uses Home SSO for the selected tenant, project and person. After a direct CRM change, choose Refresh from CRM in Inbox.

CRM record IDs, Home customer IDs and project lead IDs are different. Inbox resolves and stores the canonical binding server-side. If CRM saved but that binding failed or is ambiguous, the contact stays saved and calling remains blocked until resolved. Before dialing, Inbox reads the current CRM phone and blocks use of an outdated number.

A human call still requires the project calling connection, operator readiness, Billing capacity and contact permission. Saving a phone is not consent. Calls create call records and contact attempts against the same lead; the email conversation keeps its channel and history. Editing the CRM email does not change the email thread recipient or its approved drip. Contact edits never start calls, send messages or resume email drips. These operator actions are outside the seven Home gateway capabilities.

## Email outreach in Automations

Email outreach is enabled across tenants. Start in [Datagran Home](https://home.datagran.io/dashboard/products), select the exact tenant and project, and open Inbox. In Automations, choose email outreach and complete Audience, Message and Launch. Project access, administrator authority, current mailbox permissions, Billing and recipient eligibility remain required. Connecting a mailbox or saving a draft does not send an email.

### Connect a sending mailbox

A Home tenant administrator uses the Email section of [Connections](https://home.datagran.io/connections) to connect Gmail / Google Workspace or Outlook / Microsoft 365. Complete the provider's mailbox consent, confirm the sender, select the project and verify the connection. Existing calendar or file consent does not grant email permissions. Check that runtime setup is ready and both send and receive access are current; replies must reach Inbox to stop the drip. Tokens stay with the connection service. An Inbox project administrator without Home tenant administration needs a tenant administrator for this setup.

### Audience, research and address verification

Describe the companies, geography, relevant roles and offer. Request 10, 20, 50 or 100 potential clients; the batch form also recognizes a quantity prefix such as 'find me 20'. Review the research estimate and spending ceiling before starting. Add further batches while earlier work runs or after it finishes. Each new batch needs its own review; it does not reset existing drips or replay completed work. Keep a request's saved identity when recovering a lost response so it is not submitted as new paid work.

Research uses public web sources to find companies, people and candidate work addresses. The current research model is OpenAI Luna (`gpt-6-luna`) with web search. Sources and observation dates support each prospect's business angle; facts and inferred needs stay separate. Bounded research can return fewer qualified people than requested. Missing evidence is a research shortfall, never permission to invent a person, address or personal detail.

ZeroBounce checks candidate work addresses. Public, inferred and user-provided addresses retain their provenance. Valid, invalid, unknown and catch-all results remain distinct. An inferred address needs a valid verification result before approval; catch-all results are not treated as verified valid. Fresh verification can be reused. A reviewed recheck of an unapproved prospect is estimated and billed through the same account. A valid result describes verification evidence, not guaranteed delivery or permission to contact the person.

### Personal writing and message review

Anthropic Claude Sonnet 5.5 (`claude-sonnet-5-5`) writes personal angles, initial emails, follow-ups, revisions and approved routine replies. Provide the tone, writing samples, offer and approved claims. Prefer a relevant company initiative, hiring decision, expansion or product change that connects to the offer. Avoid invented familiarity, unrelated personal details, generic compliments and unsupported claims. If there is no sourced reason to contact someone, return that person for more research.

Aim for 50–120 words with one easy question. This is a writing target, not a delivery or conversion guarantee. For example, if a saved source says a fictional Cedar Clinic is opening a second location: 'Priya, Cedar's announcement mentions a second reception team. When patients contact the original clinic about the new one, who owns the request? We can put both locations in one inbox with an assigned owner for each inquiry. Would a short example be useful?' The expansion needs a source; the capability needs an approved claim. The possible workflow problem is a question, not an asserted fact.

Review each person's sources, angle, addresses and messages. Edit copy directly or request a separately estimated Sonnet revision. Each approved sequence has 5–20 distinct emails. Five is a product minimum, not a universal best practice or permission to keep sending after a reply. Each follow-up must add useful context: a concrete example, a relevant workflow question, an approved proof point or a polite close. Generic reminders do not replace missing evidence.

### Launch, repeat batches and Billing

Before launch, approve the exact recipients, valid addresses, copy, timing and batch budget. The sender's timezone, sending window and mailbox limits control dispatch. The first step sends separately to each approved valid address; later steps use the chosen primary address. Every logical email has its own receipt and tracking identity. Alternate addresses still count as one person and do not advance the sequence several steps. Rendering approved copy for another address does not create another AI generation charge.

Research, address checks, drafts, paid revisions and reply reviews use existing Billing estimates, rate cards, reservations, project/account spending limits and actual provider usage. The launch estimate covers the approved sequence and reply allowance. Prices come from the current Billing quote; this guide does not promise a fixed price or free verification forever. Campaign history distinguishes settled charges from pending or unknown costs. Insufficient customer funds hold paid work while inbound replies and tracking continue. Budget recovery preserves finished work and unresolved usage.

ZeroBounce capacity is shared across tenants. Verification requests are serialized with a cooldown, and the worker checks the shared credit balance before reserving customer funds for verification. If credits are insufficient or their balance cannot be checked, the same job waits and checks again after 15 minutes. The UI shows 'Waiting for email verification credits'. Waiting and the balance check do not incur a verification charge. The integration does not purchase credits or enable auto-recharge. Reusing fresh verification avoids another provider call.

### Progress and per-email activity

Automations shows unique people found, people with a valid address, people contacted at a valid address, replies, high intent, accepted steps and the next action. Activity reflects real queued, running, retrying, held or failed work. A waiting agent is shown as waiting. Adding prospects continues this work queue without restarting accepted sends.

Inspect each email's provider acceptance, available delivery or bounce evidence, detected opens, detected clicks and replies separately. Opens may come from privacy proxies and automated scanners; no open event does not prove the email was unread. Known automated activity stays separate. Provider acceptance does not prove delivery. Tracking never establishes buying intent, triggers an extra address or authorizes a follow-up. Judge writing by meaningful replies and conversations.

### Replies, intent and human control

Every incoming reply pauses the person's drip before its body is fetched for classification. Launch review offers manual handling, AI assessment with human responses, or approved routine AI answers. The paid reply allowance defaults to three reviews per person and permits up to four; it is separate from the five outbound emails. Sonnet separates buying intent from confidence and cites a reply excerpt. High intent, uncertainty, unsupported content or an exhausted allowance goes to the existing Inbox for a person to handle. Rejection stops outreach; opt-out suppresses the person and all known addresses.

Human email replies use Inbox ownership and the shared outbox. Optional routine AI answers use approved claims, the approved allowance and the same sending controls. An AI answer does not resume the drip. To continue, an administrator reviews the replies and remaining approved messages and chooses a future resume time. Accepted steps stay completed. New replies, human takeover, high intent, expired verification, partial initial-address sends or unresolved dispatches prevent continuation.

### Recovery and data handling

Inbox owns scheduling and the send ledger. After an uncertain provider send, inspect and reconcile the existing email; never create another send simply because its response was lost or a sent-folder scan is empty. A late receipt can settle usage or record delivery evidence but cannot restart stopped outreach. Message and private model content follow retention controls. Public discovery includes no prospect records, mailbox credentials or tenant billing data. Feature availability does not guarantee live deliverability, human reading, writing quality or sales outcomes.