Set Up the Outbound Email Skill
Build a database-backed outbound app with the Surface Outbound App skill: discover accounts, find contacts, and prepare inactive email drafts.
The Surface Outbound App skill guides your AI agent through setting up an outbound email app on Surface. It uses an app database for campaign records, focused tasks for research and drafting, and a read-only Overview for progress.
Agent Skill · 11 Files · Surface MCP
Surface Outbound App
Paste the complete instructions into an agent connected to Surface MCP, or download the skill for repeat use.
Copy includes every supporting instruction. Download includes the complete folder as a ZIP.
Preview Skill Files
---
name: surface-outbound-app
description: Guide a user step by step to a working email-outbound App on Surface using Surface MCP. The app owns a Neon database, a few Scheduled Tasks (an hourly Manager that starts the right stage, then Prospect, optional Qualify, Find Contacts, Draft Outreach chained by follow-ups, each running its mechanical work from a fixed script), and a published Overview. Every reply ends with one plain-language next step until the pipeline is proven end to end. Use for new outbound campaigns, adding a campaign to an existing app, moving a stage onto a script, throughput tuning, database-backed recovery, and health checks.
---
# Surface outbound app
Build and operate outbound campaigns as a Surface **App**: one durable container with a business plan, a Neon database (the AppDB), app-linked Scheduled Tasks, and a read-only Overview. **Prospect (companies) → Qualify → Find Contacts → Draft Outreach is the default shape; omit Qualify when the user does not require a qualification gate.** An hourly Manager task reads the pipeline counts and starts the stage with work, furthest along first; each stage then reruns itself while its queue has work, hands off to the next stage, or hands back to the Manager through follow-up runs, so the pipeline keeps moving for volume. Only the Manager schedules the chain, and only problems that block the whole pipeline stop a chain. Companies and contacts are separate tasks because contact work waits on qualification and spends credits differently from discovery. Every task has one job and an independently verifiable result in the database.
**Code does the mechanical work; the model only judges.** Wherever the code sandbox is available, each stage runs one fixed, hash-pinned script that makes every query, provider call, and write. The model runs the command, makes the few judgement calls a rule would get wrong, and reports. Stages that have the model retype IDs, SQL, and copy fail far more often and cost several times more. Read [references/script-stages.md](references/script-stages.md).
Use Surface MCP for every app, database, task, and UI operation. Public web research may inform seller and segment facts when permitted. Do not fall back to SQL consoles, app REST, live-app browser automation for operations, credential files, or direct provider tools. Local instruction generation, catalog-renderer previews, and authorized visual inspection of published pages are authoring/review steps; all operational reads and writes still use Surface MCP. When an MCP or provider tool is missing or misbehaves, report it as a platform issue; do not build workarounds or edit the product.
**The AppDB is the only operational record.** Accounts, contacts, decisions, evidence, provider jobs, drafts, holds, and run summaries live in its `app` schema. Never create Vault files for campaign records, queues, or checkpoints, and never grant a task `writeVault`. The Vault holds two things only: the platform-managed Overview document, which `publish_app_ui` stores itself, and one script document per script-run stage, which that task loads with `readVault: true` and checks against a hash saved in its instructions. Tasks without a script run with `readVault: false`.
**Design the schema for the customer.** Infer entities, relationships, fields, and indexes from the customer's data, approved workflow, and available providers. This skill defines operational requirements, not a table layout. Reuse an existing app's schema; create only what the workflow needs. Generate task SQL and Overview SQL against that schema during setup, then save concrete instructions so recurring tasks share one consistent contract. Read [references/database-contract.md](references/database-contract.md) for the requirements to preserve.
Use the providers the environment actually exposes (`list_scheduled_task_connections`). Clay, Apollo, Instantly, and Amplemarket are examples, not dependencies. Missing capabilities become explicit blockers or AppDB-only output, never invented tools or a false claim of a working pipeline. When the email tool is available both as a built-in Surface integration and as the provider's own MCP server, grant Draft Outreach the built-in integration: its draft tool cannot assign senders, add leads, or activate, which is the safety guarantee this skill relies on. Grant each task the least access that works: read-only wherever its calls are all reads, since a write grant exposes every write tool on that connection.
Learn each provider's real limits early and save them where the tasks and the next operator read them: items per call, jobs in flight, daily quota, credit balance, and for the email tool the daily sending capacity of the mailboxes and what else uses them. These, not batch sizes, decide how much the pipeline can deliver.
## Guided setup
This skill is a guided setup for a non-technical user. Read [references/next-steps.md](references/next-steps.md) first. **Every reply ends with a "Next step" block** computed from live MCP state: where we are in plain words, one action the user can take, and a progress count. Keep prompting until every applicable rung of the readiness ladder is done and each task has proven itself with real rows; only then switch to offering health checks. Do the steps you are authorized to do yourself; prompt only for decisions, approvals, and actions outside the chat. Keep IDs, SQL, and tool names out of the prompt block.
## Scope and intake
1. Establish seller, target segment, environment, provider preferences, whether qualification is required, and whether the user wants setup, commissioning, recurring operation, repair, or a health check. Reuse supplied answers. When an app URL is supplied, anchor every call to its environment and app IDs; otherwise resolve the environment through Surface MCP and verify returned identifiers.
2. Run `list_apps` and `get_app` for every app. **Reuse an app whose business plan covers the same seller and channel**: save a new segment as a campaign in that app's data model with its own set of tasks (Manager plus stages, named `{Campaign} · {Job}`), sharing the app's tables and Overview. Never point an existing campaign's tasks at the new campaign or widen them to serve several campaigns; each set pins one stable campaign identity, and follow-up lists only ever name tasks from the same set. Create a new app only for a different capability (another seller, another channel, incompatible operating rules).
3. Read `list_scheduled_tasks({ appId })`, `get_app_database`, `get_app_database_schema`, and `get_app_ui` before changing anything. Resolve existing campaigns using the live schema and saved task instructions; a failed run does not justify another campaign, task, or app.
4. Before creating anything, call `get_team_info` and establish which account the connector acts as using available connector identity information. The returned team owner/member list alone does not identify the authenticated user. Disclose whose account will create the tasks; if the acting account is not exposed, ask the user to confirm the connected account rather than infer it from the person chatting.
5. Present defaults briefly and proceed with them; the user can change them later. Ask only for material gaps: seller or segment, intended environment, sender mailbox and first name, and whether qualification is required. Never guess a sender name from an address.
Suggested starting values; adapt to user intent, provider latency, and current tool limits:
| Setting | Starting value |
| --- | --- |
| Cadence | Manager hourly at :00; stage tasks on demand (no schedule) and activated so they can run as follow-ups. One Manager start allows up to 10 follow-up runs in total, shared across every stage it reaches. Pace discovery to the downstream backlog, not by cadence. |
| Stage execution | Script-run when the code sandbox is available; written steps otherwise |
| Timezone | User's known timezone, disclosed; otherwise environment timezone as a disclosed fallback. Do not override a known user timezone with a connection's UTC default. |
| Prospect batch | Up to 10 new accounts per run and up to 5 existing-account repairs; batch provider calls |
| Find Contacts batch | Up to 2 contacts per account, 10 email lookups and 5 account searches per run |
| Qualify batch | Up to 10 accounts per run, including resumed work |
| Outreach batch | Up to about 4 contacts per run, each finished (saved, created, read back) before the next |
| Script-run batches | Start at the values above. Script-run stages have held about 25 accounts or contacts per run for database-only work and the provider's per-call limit (often 10) for searches; step up as [references/operating.md](references/operating.md) describes |
| Task budget | 15 minutes, 60,000 output tokens, 15 provider calls; soft stop at 8 minutes, 12 calls, ~35,000 tokens |
| Worker steps | The worker caps steps per run; keep each run one small complete unit and reserve steps for database writes and the run summary |
| Outreach | Email only; four short emails a few days apart, using the provider's native step delays |
| Publication | Inactive drafts only; no launch, activation, enrollment, or sending |
| Notifications | None by default |
These are ceilings, not quotas. Do not widen the ICP to fill them. Raise throughput only after consecutive runs fill a whole batch, commit every expected row, and verify provider outcomes within budget; raise one stage at a time and go back at the first failure. More time or tokens cannot overcome a step ceiling.
## Set up the app
Read [references/app-setup.md](references/app-setup.md) and follow its order: app → database → schema → campaign definition → tasks → Overview. Each step is idempotent and verified by reading back through MCP. Keep `get_app_database.unresolvedWrites` at zero before any seeding.
- **App**: `create_app` with a business plan from the template, or `update_app` to add the campaign to an existing plan (new revision, `expectedBusinessPlanVersion`).
- **Database**: `provision_app_database`, poll `get_app_database` until READY, inspect the catalog, and design the missing structures from the customer's actual data and workflow. Apply them with `apply_app_database_schema`; on an existing database submit only necessary additive changes and preserve its records and consumers.
- **Campaign definition**: save the campaign identity and immutable approved rules through `execute_app_database` in the chosen data model. Unapproved inputs remain unknown; each stage becomes ready only when its required inputs exist. A changed approved rule creates a new version; keep prior versions available for decisions and draft recovery.
- **Tasks**: `create_scheduled_task` with `appId`, `readAppDatabase: true`, `writeAppDatabase: true`, the stage's provider grants only, paused; stage tasks have no frequency, the Manager runs hourly. Use [references/task-instructions.md](references/task-instructions.md) to generate each task's instructions, ownership, parameterized queries, completion writes, and routing against the actual schema. Resolve every placeholder. Name tasks `{Campaign} · {Job}`; each campaign gets its own set. When an app already has campaigns, give the new Manager a different minute (for example :00, :10, :20) so campaigns don't start at the same moment. For a script-run stage, publish the script to the Vault and save its hash and startup command in the instructions ([references/script-stages.md](references/script-stages.md)). Once all tasks exist, one `update_scheduled_task` per task fills in task IDs and sets `followUpPlayIds` and `followUpConditions` as that reference lists.
- **Overview**: discover the target `publish_app_ui` schema and the catalog, pages, SQL, and revision from `get_app_ui`. Build catalog specs using [references/overview-ui.md](references/overview-ui.md), starting with the campaign's next decision and moving records/operations into drill-down. Publish with `spec` and `sql` initially; edit or add one `page` at a time, preserving the shared query and other pages. Requires a READY database and an environment Vault (`create_vault` if none exists and authorized). Do not send a top-level `html` argument.
## Choose task boundaries
Define each task by its one job, committed inputs, eligibility predicate, owned tables and columns, allowed operations, cadence, budget, and observable completion condition. Start with the default shape and reshape it as the campaign shows where work actually piles up; the task layout is a working decision, not a fixed design.
**Split a task when** its steps compete for one run's budget (one queue routinely starves another), runs keep ending at the call, step, or time limit, a step waits on a different stage than the rest of the task (contact research waits on Qualify, discovery does not), or a step needs its own cadence, provider spend, or permissions. Examples: a CRM Fit gate, splitting email lookups from contact research when they need different providers, or Reply Sync when requested.
**Merge or drop a task when** it is empty run after run, its work is a quick database-only step another task already reaches, or the user wants fewer moving parts.
**Keep side jobs out of the chain.** A job that does not feed the next stage (reply and outcome sync, account notes, a second email-lookup pass) keeps its own schedule and its own self-rerun. The Manager neither starts it nor counts it.
**How to reshape:** pause the affected tasks; move the steps, their queue SQL, column ownership, the pipeline counts column, and the follow-up lists and routing lines of the neighbouring tasks and the Manager in one change (create or edit the tasks with instructions compiled from [references/task-instructions.md](references/task-instructions.md), remove the moved steps from the source task, and make its recovery skip the moved operations so in-flight jobs finish with the new owner); run each changed task once and confirm the work landed with the new owner and nothing is processed twice; then accept and resume. A task cannot be edited mid-run and pausing ends its chain: pause, wait until idle, update, read the task back, activate, and let the Manager restart it. One writer per column group at all times. Mention the change and the reason to the user in plain words.
Without Qualify, Find Contacts runs right after Prospect and Prospect owns the evidence check inside its fit assessment. Draft Outreach requires current fit approval and saved supporting evidence, but no qualification decision. Record that choice in the campaign rules; omit unused qualification structures in a new schema.
## Verify and commission
Setup verification is read-only: `get_app`, `get_app_database_schema`, `query_app_database` on the definition, `get_scheduled_task` for each task (grants, schedule, timezone, instructions), `get_app_ui`. Check that eligibility rules agree across the definition, the saved queue SQL, and existing holds; account fit, qualification, evidence eligibility, contact readiness, and enrollment are separate facts.
**Run autonomously.** Starting this skill authorizes setup, test runs, adjustments, acceptance, and schedule activation without further confirmation, as long as no email can be sent. The hard line is sending: never activate, launch, resume, or enroll anything with the email provider, never set `sending_authorized` or `live_activation_authorized` to true, and never grant a task a provider operation that sends. Surface schedule activation is fine; provider campaign activation is not. The single exception is a user who explicitly asks for live enrollment after the draft pipeline is proven: then follow [references/live-enrollment.md](references/live-enrollment.md), which needs the provider account owner's written confirmation, and nothing less. Ask the user only for facts and approvals the skill cannot supply (seller, segment, sender identity, email copy approval, reconnecting a provider) and for anything that would send.
As soon as a task's prerequisites are met (rules approved, required providers connected and granted, database ready; appdb_only Outreach needs no email provider), run it once with `run_scheduled_task`, inspect the result, fix what you can (instructions, definition version, grants, holds), rerun, and move to the next stage. Keep a commissioning loop of at most three attempts per stage before reporting a blocker. Commission in dependency order: Prospect, Qualify (if present), Find Contacts, then Draft Outreach, each once. After each run inspect `get_scheduled_task_run` activity and write outcomes, then verify rows with `query_app_database` and the run's saved summary. A COMPLETED label is not persisted work. Accept a run with `accept_scheduled_task_run` once rows pass review, then `activate_scheduled_task`: a stage task has no schedule, so activating it only makes it available as a follow-up. Once every stage is active, run the Manager once, check that its routing line names the right stage and that the follow-up was queued, accept it, and activate it. The pipeline counts as on only after the first scheduled Manager run fires by itself and the chain it starts calls the right tasks: the Manager queues the stage with work, and each stage reruns, hands off, or stops as its routing line says. Each slot can fire up to an hour after its cron time, so check back within about two hours; no scheduled Manager run after that is a platform issue to report, not a reason to add schedules or start stages by hand. Tell the user when the pipeline is confirmed working, not when it is merely activated. Manual test runs may chain into stages that are already active; that is expected. Schedule activation is not send authorization: drafts stay inactive in the provider until the user activates them there.
Change a proven stage on a copy first. To move a stage onto a script or change its script, test a paused copy of the task with the same grants and a batch of 1 to 3, compare its rows with the current behavior, then switch the real task, keep the previous instructions for rollback, and delete the copy. Validate one release with a clean live run before publishing the next.
During commissioning, a follow-up skipped because the downstream task “does not have an accepted run” is expected until that stage is accepted and activated. Continue commissioning in dependency order; it is not a reason to add schedules or recreate tasks.
After activating the Manager, arrange one check-in about 80 minutes later if the session has an available reminder/scheduling tool; confirm the reminder was actually created. Keep it in the current session, not an outbound campaign task or an external notification. Otherwise tell the user when the scheduled-run check is due. Avoid repeated polling, and leave rung 16 pending until an actual scheduled run and its follow-up are observed.
Read [references/recovery.md](references/recovery.md) on failures, uncertain writes, authentication errors, truncation, or count mismatches. Do not repeatedly run blocked tasks.
## Keep it proportionate
The rules in this skill exist for two outcomes: **nothing is sent** (unless live enrollment was explicitly authorized), and **saved rows and drafts are correct**. Everything else is judgment; adapt to the provider, the data, and what the user asks for.
- Verify what you can observe directly: rows exist, a draft is inactive, its emails contain the approved copy. Rely on a tool's documented contract for what the provider cannot report (for example, which mailboxes are attached to a draft the task just created). Never try to prove an absence the provider does not expose.
- If a check cannot be done with the exposed tools, note it in the run summary and continue. Do not scan whole accounts, probe undocumented endpoints, or invent stand-in IDs to make a check pass.
- The same error twice after a change is a tool or platform problem, not a prompt problem. Stop and report it with the exact error instead of rewriting instructions again.
- Do not add definition rules, holds, or verification requirements the user did not ask for. A hold must name something a person or a later run can actually do.
- Saved task instructions stay the compiled contract for that stage and app schema. Do not turn a task into a one-off investigation; if a single diagnostic run is unavoidable, restore its operating instructions right after it.
- IDs belong to one system: app table IDs are never provider IDs, and provider IDs come only from provider responses.
- Report numbers from a query, not from memory or an estimate, and say which statements are observed and which are inferred. Check the thing itself: a setting by reading the task back, an email by reading a delivered one.
- A lookup proves nothing until it has matched a known positive. A gate that clears nearly everything (a CRM check, an exclusion list) may be matching on the wrong key.
- Clean up what you create: probe tasks, test copies, one-off audits, test records.
- Defaults are fine. Optional settings left null mean "use a sensible default", not "blocked waiting for approval".
## Monitor
A health check reads the Overview data (`get_app_ui` SQL through `query_app_database`), row counts per stage, saved run summaries over a stated interval, unresolved holds in the actual schema, `get_app_database.unresolvedWrites`, and `list_scheduled_task_runs`, including whether each Manager run's follow-up was queued and how far each chain got. Separate what the next run can advance from what needs a rule, data, capability, or user decision. A health-check request alone does not authorize edits or runs.
For ongoing monitoring, throughput tuning, and a pipeline that has gone quiet, read [references/operating.md](references/operating.md). The aim is a pipeline that needs no operator: when authorized to restart it, start the Manager, never a stage, and fix the Manager's query or a stage's rule rather than starting runs by hand each hour. Name the limiting factor in every report; once the limit is outside the pipeline (sending capacity, a provider quota, credits, a campaign rule), more runs and larger batches add nothing.
## Finish
Until the pipeline is fully working, "finish" means the next-step block, not a final report. When it is working, return the app URL, task links, schedules and timezone, paused/armed state, provider and copy strategy, verified counts by stage, open holds, and remaining blockers. Say whether anything ran and whether contacts entered inactive drafts. Unless live enrollment was explicitly requested and authorized, no live campaigns or prospect messages are part of this skill; when it was, report confirmed enrollments, flagged leads, and the sending capacity separately from drafts. Report SQL checks, published UI revision/pages, and actual visual inspection separately. Without a renderer, explicitly label the UI "visually unverified" and give the app link and specific page/drawer checks. A successful publication or working task pipeline is not visual verification.
Installing manually? Keep all 11 files together. SKILL.md uses the reference files.
The skill is designed to take setup through test runs and recurring operation once the required campaign rules, copy, and connections are ready. Research runs may consume provider credits. By default, it prepares inactive drafts without enrolling recipients or sending emails. Optional live enrollment requires a proven draft pipeline, an explicit request, and written authorization from the email provider account owner. Adding recipients to a live sequence starts outreach.
What You Will Set Up
| Task | What It Does | What It Saves |
|---|---|---|
| Manager | Checks the pipeline hourly and selects the stage with actionable work, prioritizing downstream work. | Counts and a routing summary. |
| Prospect | Finds companies that match your target segment and checks account fit. | Company records, sources, and campaign-specific fit decisions. |
| Qualify | Checks supporting evidence when your campaign requires a separate qualification gate. | Decisions, evidence, and pending research. |
| Find Contacts | Researches approved personas at eligible companies and looks up emails. | Contact records, sourced emails, and company associations. |
| Draft Outreach | Personalizes the approved email sequence for eligible contacts. | Rendered copy and, where supported, verified inactive provider drafts. |
Only the Manager has an hourly schedule. The skill configures stages to run through follow-ups: continue their own queue, hand work to the next stage, or return to the Manager. Qualify is optional; without it, Prospect owns the required outreach evidence checks.
The app database holds accounts, contacts, evidence, provider job IDs, drafts, holds, and run summaries. The Overview presents those records and task health. The skill reuses a compatible app for the same seller and email channel, with separate campaign rules and task sets for each segment.
When a code sandbox is available, fixed scripts handle queries, provider calls, and writes, while the model handles judgment calls. Each stage loads its script from the Vault and checks it against a saved hash before running.
If the available email tools cannot support inactive drafts, the skill can use a database-only strategy: save and verify rendered copy in the app without creating provider drafts. It reports that distinction explicitly.
Before You Start
You will need:
- An AI agent connected to Surface MCP. To install the ZIP for repeat use, your agent also needs local skill support.
- Access to app, database, scheduled-task, and Overview tools through MCP. Ask your agent to verify which tools and connections your environment exposes.
- Connected research providers for the discovery and contact work you want. Provider-backed drafting also needs a suitable email connection.
- Your company website, target accounts, contact personas, exclusions, and any qualification criteria.
- Approved email copy and a confirmed sender name and mailbox before drafting.
Connect your agent using Surface MCP Setup. The skill checks the target environment and connected account before creating tasks, and asks for missing business details or provider connections as needed.
Choose How to Use It
Copy instructions is the quickest way to start. Paste the combined Markdown into an agent connected to Surface MCP, then provide your campaign details. All supporting instructions are included; no local skill files are needed.
Download skill is the reusable installation option. Extract the ZIP and place
the entire surface-outbound-app folder in your agent's skills directory.
Use your agent's installation instructions to choose the location.
Keep all 11 files together:
surface-outbound-app/
SKILL.md
agents/
openai.yaml
references/
app-setup.md
database-contract.md
live-enrollment.md
next-steps.md
operating.md
overview-ui.md
recovery.md
script-stages.md
task-instructions.mdSKILL.md is the entry point. The references cover app setup, database records,
guided next steps, the Overview, task instructions, script-run stages, ongoing
operation, recovery, and optional live enrollment. Copying only SKILL.md leaves
the instructions incomplete.
Set Up Your First Campaign
Paste this prompt after the copied instructions, or invoke the installed
surface-outbound-app skill with these details:
Use the Surface Outbound App skill to set up my outbound email campaign.
Company: [company name and website]
Surface environment or existing app: [team, environment, or app URL]
Target accounts: [industry, geography, company size]
Target contacts: [roles or personas]
Qualification: [required criteria, or no separate qualification stage]
Offer: [what we can help with]
Exclude: [customers, competitors, domains, or other exclusions]
Preferred providers: [names, or inspect my available Surface connections]
Sender: [confirmed mailbox and first name]
Timezone: [for example, America/Los_Angeles]
Reuse a compatible app or create one, set up its database and campaign rules,
create the Manager and stage tasks, and publish the Overview. Ask me for
missing details and approval of the email copy. Once prerequisites are ready,
test the stages, verify saved results, and enable the Manager and follow-ups.
Keep drafts inactive. Do not enroll recipients or send emails.The agent should guide you through missing decisions one at a time, with a progress count and a plain-language next step. Its default workflow includes commissioning and activation of Surface tasks. To limit the work, add: "Setup only. Leave all tasks paused; do not run tests or enable recurrence."
Review and Verify the Pipeline
Open the app and task links returned by your agent. Review:
- Campaign rules: target accounts, personas, exclusions, qualification, and approved copy and sender.
- Overview: the campaign's next decision, with companies, contacts, drafts, evidence, and operational detail available through focused pages and row drawers. A published page is not proof of visual inspection; without a renderer, the skill reports "visually unverified". Sidekick review buttons request review, never enrollment, campaign activation, or sending.
- Task configuration: campaign scope, provider access, timezone, limits, and the Manager's schedule and follow-up routing.
- Saved outcomes: actual database rows and complete rendered copy; for provider drafts, the saved provider ID, content readback, and inactive state.
The skill starts with bounded batches and raises throughput only after runs consistently save their expected work. Provider results are persisted promptly, exact jobs are resumed, and the run summary is saved last. A COMPLETED label alone does not establish that records or drafts were saved.
Activation alone is also not proof that recurrence works. The skill calls for checking an actual scheduled Manager run and the follow-up it starts. If that check is still pending, the agent should say so and give you a time to check back. Live enrollment requires a separate explicit request and the email provider account owner's written authorization after the draft pipeline is proven.
Monitor Progress and Recover
Ask your agent to "Check the pipeline for [campaign] over [time window]." It should inspect current database records, saved summaries, task activity, unresolved writes, and follow-up routing. Reports separate actionable work, waiting retries, and holds that need a person to act. A health check alone does not authorize edits or extra runs.
If a run fails after a provider change, that change may still exist. The skill directs the agent to reconcile saved operation IDs and actual provider state before retrying, so failed runs do not become duplicate research or drafts. Operational records, campaign queues, and checkpoints stay in the app database. The Vault holds the platform-managed Overview and one script document per script-run stage; tasks can read those scripts but cannot write to the Vault.
Ready to Get Started?
See it on your own site, or open the app and build the first form.