# 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. Choose Automations → New automation. Choose CRM & pipeline for stage changes, Email outreach to find new people or use an uploaded list, or Inbox for conversation routing and no-reply follow-ups. Email outreach has Contacts, Message and Review steps. Project access, administrator authority, Datagran CRM connected to this project's Inbox, current mailbox permissions, Billing and recipient eligibility remain required. Connecting a mailbox or saving a draft does not send an email.

### Choose an automation

| Goal | Choice after New automation | What starts the work |
| --- | --- | --- |
| Find new companies and people to email | Email outreach | Save the setup, then review a research estimate and request a batch of 10, 20, 50 or 100 people. |
| Email contacts supplied in CSV or Excel | Email outreach → Upload a list | Save the setup, upload and check the list, select contacts, then approve a preparation estimate. |
| Email a saved contact after a stage change | CRM & pipeline → Personal email sequence | Enable the stage trigger. New matching contacts enter a queue for separate preparation and sending approval. |
| Follow up on a Home pipeline stage | CRM & pipeline → WhatsApp, SMS or a team task | Save a draft, then activate it. Automatic messages use WhatsApp or SMS; manual email and call options create tasks for the team. |
| Route new WhatsApp or SMS conversations | Inbox → When a conversation starts | Review and publish the incoming conversation rules. Saving rules as a draft does not publish them. |
| Follow up after no reply | Inbox → When someone hasn't replied | Select Home pipeline stages and the wait since the team or agent's message. Save the draft, then activate it. |
| Build a WhatsApp or SMS sequence | Inbox → Create a message sequence | Save and activate the sequence, then select it in the appropriate incoming conversation rules. |

Basic follow-up setup uses Start, Message, Timing and Review. Email outreach uses Contacts, Message and Review; CRM email uses Trigger, Message and Review. If these choices or the required stage source are unavailable, report the missing interface or connection. Public guidance does not prove that every component is deployed in the current environment.

### Gather the inputs

Use existing user instructions and saved settings first. Ask for missing choices that affect scope, spending or sending. Do not invent approved claims, recipient permission, a budget or a sending identity.

| Input | Where to use it |
| --- | --- |
| Exact client and project; automation name | Select the workspace in Home, then enter Automation name. |
| New prospects: company type, geography, business signals, exclusions and roles | Contacts → Find contacts → Who do you want to reach? and Who would get value from your offer? |
| Uploaded contacts: CSV or .xlsx file with email and optional name, company, website, role and notes | Contacts → Upload a list. Optional contact context does not replace the uploaded recipient. |
| Saved contacts: CRM connection or Home pipeline and selected stages | Trigger → Where are the stages? Select the displayed stage labels. Native CRM choices use the connection name followed by · People. |
| Offer and desired response | Message → What can you help with? and What reply would you like? |
| Tone, supported facts and optional writing sample | Message → How should the emails sound? Expand Add your voice and proof. Empty optional fields are not permission to invent evidence. |
| Sending mailbox, timezone, weekday window and daily limit | Review → Send from, Sender timezone, Weekday sending starts/ends and Daily email limit. Select the ready mailbox before saving if finished drafts and sending are required. |
| Automation budget in USD and tracking preference | Review → Automation spend limit, USD and Track opens and clicks per email. A spending limit does not add Billing funds. |
| New prospects: 10, 20, 50 or 100 people, batch focus and maximum batch spend | After Save email automation, use Find your next potential clients. Each additional batch has its own estimate. |
| Saved contacts: approval of each contact's preparation cost | After Enable stage trigger, use CRM queue → Review preparation cost → Prepare emails. This uses the saved contact, not a discovery batch size. |
| Reply handling and paid AI allowance | Review people and launch → When someone replies. Choose My team handles replies, Score; my team responds, or Score and answer questions. AI modes offer up to 3 or 4 reviews per person. |
| Recipient permission, valid addresses, copy and sequence timing | Review each person and the sending estimate before approving a batch. Review at least five distinct emails; every reply pauses the drip. |

### Check readiness and resolve blockers

Read existing status first. A read-only walkthrough does not authorize saving configuration, checking a provider connection, granting access, adding funds or starting paid work.

| Check | What must be ready | If it is missing |
| --- | --- | --- |
| Workspace and Inbox access | Home → Product access and Product roles: Inbox enabled and current Inbox Admin access to the exact project. Home tenant administrators inherit product administration. | A Home tenant administrator enables Inbox or assigns the project product role. Reopen Inbox from Home after access changes. |
| Mailbox setup and selection | Home → Integrations → Email: correct sender, exact project, ready runtime, current send and receive permissions. Choose the account under Review → Send from, or save first and attach it in the saved automation. | A tenant administrator completes Google or Microsoft consent and connects the mailbox to Inbox. Calendar consent is insufficient. Research and verification can run without a sender, but drafting and sending cannot. In a saved automation, Send from → Connect Gmail or Outlook opens Home in a new tab. Return, refresh accounts if needed, choose the account and select Use this email. Attaching the first sender preserves research and starts no paid work or send. Open the research batch and select Prepare emails or Finish preparing missing emails or checks, then review the preparation estimate. Current valid checks and saved drafts are reused. Approve preparation and review the finished emails separately before launching. An existing sender cannot be replaced through this control. |
| CRM stage source | Home pipeline stages, or an accessible Datagran CRM connection with this project's Inbox crm.read grant and working People stage feed. | Resolve the connection or mapping in Home. Native CRM preparation requires a successful sync within five minutes and no current sync error. Do not substitute another CRM, project or contact. |
| Billing funds and limits | Home → Usage & billing: project Billing mapping, account funds, remaining automation budget and current preparation and sending estimates. | Funding or limit changes need authorization. Missing mapping or rates need the Billing administrator or Datagran support. An estimate does not reserve funds. |
| Recipient and message review | Review people and launch: completed research, sourced angle, verified address, personal messages and a current sending estimate for selected people and reply policy. | Wait for unfinished work or resolve the displayed issue. Do not bypass suppression, invalid or catch-all addresses, or uncertain prior sends. Refresh expired or changed estimates. |
| Reply checks after approval | Mailbox reply checks: correct sender and a recent completed check. Sending waits for current reply ingestion. | Follow the connection or recovery message. A scheduled check is not a completed check. |
| Shared verifier capacity | Waiting for email verification credits means the saved job is waiting for ZeroBounce capacity. | Keep the existing job. It rechecks after 15 minutes without charging for the wait. This wait does not purchase credits. |

### Know which steps change state or spend money

1. Opening setup and moving between steps does not save anything. Save email automation saves discovery configuration; Enable stage trigger saves CRM configuration and enables queue enrollment. Neither starts paid preparation or sends emails.
2. Estimate research or Review preparation cost shows a quote without reserving funds. Start research for N people or Prepare emails authorizes research, verification and drafting within the reviewed limit. Drafting also requires the automation's saved sender.
3. Review sending estimate shows the selected people, sequence and reply allowance. Approve N people and queue emails authorizes sending in the configured window.
4. Another discovery batch or CRM contact needs its own preparation review and sending approval. Existing completed work remains completed.

External agents need authorized browser access for these setup actions. Home's delegated tools provide reads; the seven trusted Inbox gateway capabilities cannot create or launch email outreach. An agent without browser access can gather the inputs and guide the user through the interface. Never request a platform secret or invent an outreach write tool.

### Use an uploaded contact list

When the user supplies a customer list, recommend Upload a list in the saved email automation. Accept CSV and .xlsx up to 5 MB and 1,000 contact rows. Each recipient needs an email; all other fields are optional. Select a populated worksheet for multi-sheet files. Check the suggested columns, correct rows if necessary and save changes. Original values remain available. Recent lists retain saved mappings, corrections and preparation batches across page visits. Uploading, mapping and previewing start no paid work and create no CRM leads.

Review Ready, Needs correction, Duplicate, Do not contact, Already prepared and Identity needs review counts. Select ready rows or choose the exact number to prepare, such as 50. Estimate preparation shows research, email checks and writing costs for only those rows. Prepare contacts authorizes work within the chosen limit. Larger selections use bounded preparation batches under one total approval. Sending has a separate review and estimate.

Research uses the uploaded address and supplied business details. It never substitutes an address or finds other people to fill the selection. A public business match needs source evidence. Consumer mailbox addresses and shared company mailboxes do not prove a person's identity. If no business is confirmed, drafts use only supplied details and approved claims, show Business not confirmed and omit invented greetings or facts. Conflicting identities need correction or review before preparation can continue. The imported email stays fixed in the draft editor. Accepted sends create or match the CRM lead with Contact attempted status; import preview and preparation do not.

If a preparation response is lost, use Check previous preparation. It checks the saved request rather than starting another one. Reopening an already prepared list does not repeat paid work. Resume incomplete batches through their existing preparation estimate and recovery controls. Replies, opt-outs, mailbox checks and current CRM readiness retain the usual sending rules.

### CRM-triggered email sequences

Choose New automation → CRM & pipeline → Personal email sequence. Select the stage source and stages, describe your offer and voice, then review timing and the spending limit. Enable stage trigger starts the queue. It does not buy research or send emails. A contact enters an automation once, after a new stage change. Contacts already in the stage before activation are not imported.

Supported sources are Home pipeline stages, including Salesforce changes mapped into Home, and People stages in an explicitly connected Datagran CRM. Native CRM polling needs the selected project's current Inbox crm.read grant and project credential. Other CRM contact integrations do not automatically provide stage triggers. Company and opportunity stages are not native email triggers.

Open the automation's CRM queue. Review preparation cost shows a Billing estimate for that contact. Prepare emails authorizes the estimated research, ZeroBounce verification and Sonnet drafting through the existing Billing limits. Research uses the saved CRM name and work email. It cannot substitute another recipient or guessed address. Review the sourced angle, valid address and at least five emails, then approve sending. Mailbox readiness, reply handoff and opt-out rules remain the same as researched email outreach.

Home delivers stage events directly. Datagran CRM is normally checked about once a minute in pages of 50 people; larger queues can take longer. The connector rescans changes since activation and deduplicates each person. If it observes a person leaving the selected stage while preparation is still waiting, that entry is skipped. Polling is not a real-time eligibility check. After preparation is queued, later stage changes do not cancel its batch or approved drip. Skipped or previously enrolled contacts do not enter the same automation again.

Stage changes while a native CRM trigger is paused can be found on resume if the person still matches; Home events enroll contacts only while active. Missing names or valid email syntax block preparation. The queue shows up to 100 contacts, oldest waiting first. Use Check saved request after an uncertain preparation response. Pause automation and Resume automation control the automation; they do not resume an individual drip paused by a reply.

### 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, user-provided and CRM-saved addresses retain their provenance. Valid, invalid, unknown and catch-all results remain distinct. Every approved address needs current valid verification; 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. In prospect discovery, the first step sends separately to each approved valid address; later steps use the chosen primary address. CRM preparation uses the one saved email from its reviewed contact snapshot. 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.