Action and system primitives
Primitive 1: find, verify, or resolve
People use "reverse email search" to mean a few different jobs. Separate them before you run anything.
| Job | Starting point | Desired output |
|---|---|---|
| Find email address by name | first name, last name, company | work_email, email_status |
| Verify an email before outreach | existing email | email_status, reason if available |
| Resolve identity from known email | person, company, title if available | |
| Waterfall email lookup from a list | CSV with names, domains, or URLs | email, status, provider context |
The human problem is not "can we find an email?" It is "can we trust this email enough for the next step?"
Primitive 2: the status-first email prompt
You are helping me find or verify work emails.
Input file: contacts.csv
Goal: prepare a safe outbound-ready sample.
Required output fields: email, email_status, verification_status, next_step.
First inspect the CSV headers and tell me whether this is an email-finder, verifier, or reverse-lookup job.
Run 10 rows first.
Do not invent emails.
Mark rows as not_found or needs_review when the result is incomplete.
After the sample, summarize how many rows are ready for outbound.
That prompt gives the human a usable acceptance check before the skill output becomes a script or Workflow.
Primitive 3: outbound-ready email output
| first_name | last_name | domain | email_status | next_step | |
|---|---|---|---|---|---|
| Ada | Lovelace | example.com | ada@example.com | verified | ready_outbound |
| Grace | Hopper | example.org | not_found | retry_provider |
The next_step column is what makes the result operational. It tells the operator, script, or Workflow what to do next.
How the primitives move through skills, scripts, and Workflows
Start with the Deepline skill. The skill is the primary way to ask for email lookup, inspect sample rows, and decide whether the results are trustworthy enough for outbound.
When the sample is approved, promote the same lookup contract into a script for repeatable list work or a Deepline Workflow for scheduled enrichment, review, and downstream handoffs.
For provider email actions, use:
POST /api/v2/integrations/{toolId}/execute
The {toolId} must be a provider email tool id, not a waterfall alias.
For play-backed email enrichment, POST /api/v2/enrich/compile returns an enrich config. That response is not itself a play artifact and cannot be sent directly to the play check or run routes.
The CLI/SDK converts the enrich config into play source, bundles a play artifact, checks it with POST /api/v2/plays/check, and starts it with POST /api/v2/plays/run. API clients must provide generated source and a bundled artifact to check or run, or use a supported named prebuilt play reference. Waterfall aliases such as name_and_domain_to_email_waterfall, person_linkedin_to_email_waterfall, and personal_email_waterfall are composed play-backed flows, not atomic provider operations.
Script pattern after the skill works
Use direct provider execution only after the skill has helped select and validate a specific email provider action:
deepline tools execute leadmagic_email_finder \
--input '{"first_name":"Ada","last_name":"Lovelace","domain":"example.com"}'
Use deepline enrich --with for a prebuilt waterfall alias:
deepline enrich --input contacts.csv \
--with '{"alias":"email","tool":"name_and_domain_to_email_waterfall","payload":{"first_name":"{{first_name}}","last_name":"{{last_name}}","domain":"{{domain}}"}}' \
--output contacts-with-email.csv
The workflow remains repeatable because the JSON object spec declares the output alias, the play-backed tool alias, and the payload mapping.
Quality check before deploying a Workflow
No no-spend generic workflow-specific test route was found for reverse email search or email enrichment. POST /api/v2/integrations/test may execute real provider paths for provider-backed cases and must not be documented as safe test validation.
For waterfall-backed email workflows, distinguish enrich config compilation from play artifact generation. POST /api/v2/enrich/compile returns an enrich config. The CLI/SDK then generates play source and a bundled artifact that can be validated with POST /api/v2/plays/check before execution. That is workflow preflight, not a safe provider email test endpoint.
Before a full run, inspect the sample for status coverage, empty values, and guessed-looking emails. The right output is a trustworthy contact list, not a maximum-fill spreadsheet.
Cost and billing behavior
Keep billing language Deepline-facing. In BYOK mode, customers bring their own data-provider keys and Deepline does not add a platform fee for that mode. In managed mode, Deepline uses credit-based operation billing.
Single-provider enrichment commonly leaves coverage gaps. Waterfall enrichment improves match rates by querying multiple providers in sequence, but the lift varies by ICP and region. Start with a small sample, inspect the output fields, then scale the reverse email search workflow when the skill has produced the right acceptance criteria.