Research and outreach

This guide builds a two-part pipeline: an agent task that researches a company from its domain and returns a typed result including a subject line and body, and an email batch that runs the task once per row of your list, shows every draft for review, and sends only when you create a send.

Only send to people who opted in. Mail goes through your own Resend account, and Resend’s acceptable-use policy forbids cold outreach, purchased lists and scraped contacts. See email overview.Drafting has no spend cap. Every row runs the task on your provider keys, plus whatever its integrations charge per call, whether or not the draft is ever sent.

You need: an LLM provider key, a Tavily API key, a Resend account with a verified sending domain (email setup), and the EDITOR role.

1. Connect Tavily and narrow its tools

curl -sS https://api.talqing.com/v1/integrations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "tavily", "display_name": "Tavily (research)", "credentials_ref": "tvly-your-api-key"}'

GET /v1/integrations/{integration_id}/mcp-tools lists the tools live from the provider, which also proves the key works. A new integration approves every tool (allowed_tools: null); narrow it to the two this task needs, so the model chooses from fewer:

curl -sS -X PATCH "https://api.talqing.com/v1/integrations/$INTEGRATION_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_tools": ["tavily_search", "tavily_extract"]}'

The list is replaced whole and cannot be empty. See MCP servers.

2. Write the task

task.json

{
  "config": {
    "name": "Research a company and draft an opener",
    "prompt": "You research a company from its website and draft one short email to a person there.\n\nThe company's domain is {{vars.domain}}. The recipient is {{vars.first_name}}, whose role is {{vars.role}}. They downloaded our warehouse capacity planning guide, which is why we are writing.\n\n1. Search for the company and read their own site. Prefer what they publish about themselves over directory listings.\n2. Work out what they sell, who buys it, and one specific, recent thing worth mentioning: a new location, a product launch, a hiring push.\n3. Write a subject line and a body of at most 120 words, addressed to {{vars.first_name}}, that names that one thing and connects it to warehouse capacity planning. No flattery and no claim you did not read somewhere.\n\nIf you cannot find something specific and true, send null for the subject and body. Finish by calling submit_result.",
    "llm": { "provider": "openai", "model": "gpt-5.6-luna", "reasoning_effort": "medium" },
    "mcps": [{ "integration_id": "c41d8e37-25a9-4f60-b3d8-9e07a15c4b62" }],
    "vars": [
      { "name": "domain", "description": "The company's website domain, e.g. asha-textiles.com", "required": true },
      { "name": "first_name", "description": "The recipient's first name", "required": true },
      { "name": "role", "description": "The recipient's job title, as they gave it", "default": "" }
    ],
    "output": [
      {
        "name": "company_name",
        "type": "string",
        "required": false,
        "description": "The company's trading name as it appears on their own site. Send null if the domain resolves to no company you can identify."
      },
      {
        "name": "specific_detail",
        "type": "string",
        "required": false,
        "description": "The one recent, checkable thing worth mentioning, in one sentence with no adjectives. Send null if you found nothing specific."
      },
      {
        "name": "subject_line",
        "type": "string",
        "required": false,
        "description": "A subject line under 60 characters that names the company. No exclamation marks, no capitals for emphasis. Send null if specific_detail is null."
      },
      {
        "name": "email_body",
        "type": "string",
        "required": false,
        "description": "The email body, at most 120 words, addressed by first name, naming the specific detail and connecting it to warehouse capacity planning. Plain text with line breaks, no signature, no subject. Send null if you could not write something specific and true."
      }
    ],
    "max_steps": 12,
    "timeout_seconds": 240
  }
}

curl -sS https://api.talqing.com/v1/tasks \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d @task.json

What matters in this config:

vars are the inputs. The batch fills them from CSV columns of the same name. A required variable with no column and no default is refused when the batch is created.
Each output description is the prompt for that value. It becomes the argument description of the generated submit_result tool. Say what good looks like and when to send null.
required: false lets a field be null. Every field must still be sent, so “could not find it” is explicit rather than a missing key. See inputs and output.
max_steps (default 25, max 50) counts model → tools → model rounds, not tool calls. timeout_seconds (default 300, max 600) is wall-clock and usually the real bound. See errors and limits.

3. Run it once and read the result

task_version: "draft" runs the unpublished config. The request blocks until the run finishes, so set your client’s timeout above timeout_seconds (the Python SDK defaults to 30 seconds).

curl -sS -X POST "https://api.talqing.com/v1/task-runs" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{"task_id": "'"$TASK_ID"'", "task_version": "draft", "vars": {"domain": "asha-textiles.example", "first_name": "Priya", "role": "Head of Operations"}}'

const run = await talqing.taskRuns.create({
  createTaskRunRequest: {
    task_id,
    task_version: "draft",
    vars: { domain: "asha-textiles.example", first_name: "Priya", role: "Head of Operations" },
  },
});
console.log(run.status, run.steps_used, run.attempts, run.output);

run = talqing.task_runs.create(
    task_id=task_id,
    task_version="draft",
    vars={"domain": "asha-textiles.example", "first_name": "Priya", "role": "Head of Operations"},
)
print(run["status"], run["steps_used"], run["attempts"], run["output"])

Check, in order:

Field	What to look for
`trace`	Every tool call with arguments and result. Shows whether it searched for the right thing
`steps_used`	At `max_steps`, the run is being cut off rather than finishing
`attempts`	Above 1 means the model failed to call `submit_result` and was re-prompted; each attempt is billed
`error.type`	On failure: `no_output` (fix the prompt), `step_limit`, `configuration` (missing key or deleted tool)

Run it on a domain you know well, so you can tell a true sentence from a plausible one. When it is right, publish — a batch uses the published version:

curl -sS -X POST "https://api.talqing.com/v1/tasks/$TASK_ID/publish" \
  -H "Authorization: Bearer $TALQING_API_KEY"

4. Connect Resend

curl -sS https://api.talqing.com/v1/integrations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "resend", "display_name": "Resend (outreach)", "credentials_ref": "re_your_resend_api_key"}'

curl -sS -G https://api.talqing.com/v1/email/senders \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  --data-urlencode "integration_id=$RESEND_INTEGRATION_ID"

The senders call returns the account’s verified domains, read live. Any address on a verified domain can be from_email; one on an unverified domain is refused.

5. Create the batch

Each row has one flat column space: your CSV’s columns plus the task’s output fields. field_map points to, subject and body at names in that space — a CSV header or a string output field. Here the address comes from the CSV and the words from the task.

curl -sS https://api.talqing.com/v1/email/batches \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guide downloads, week 36",
    "task_id": "5e2a7b91-0c34-4d6f-8a12-b93f5c7e2d61",
    "integration_id": "a41f6c2d-8b17-4e93-9d05-2c7e6f31b840",
    "from_email": "priya@yourdomain.com",
    "from_name": "Priya at Northwind",
    "reply_to": "priya@yourdomain.com",
    "body_format": "text",
    "field_map": { "to": "email", "subject": "subject_line", "body": "email_body" },
    "recipients": [
      { "input": { "email": "priya@asha-textiles.example", "domain": "asha-textiles.example", "first_name": "Priya", "role": "Head of Operations" } },
      { "input": { "email": "arjun@ravi-foods.example", "domain": "ravi-foods.example", "first_name": "Arjun", "role": "Supply Chain Lead" } }
    ],
    "timezone": "Asia/Kolkata",
    "window": { "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "draft_concurrency": 5
  }'

const batch = await talqing.email.batches.create({
  createEmailBatchRequest: {
    name: "Guide downloads, week 36",
    task_id: "5e2a7b91-0c34-4d6f-8a12-b93f5c7e2d61",
    integration_id: "a41f6c2d-8b17-4e93-9d05-2c7e6f31b840",
    from_email: "priya@yourdomain.com",
    from_name: "Priya at Northwind",
    reply_to: "priya@yourdomain.com",
    body_format: "text",
    field_map: { to: "email", subject: "subject_line", body: "email_body" },
    recipients: rows.map((input) => ({ input })), // rows: Record<string, string>[] from your CSV
    timezone: "Asia/Kolkata",
    window: { start: "09:00", end: "18:00", days: [1, 2, 3, 4, 5] },
    draft_concurrency: 5,
  },
});

import csv

with open("list.csv", newline="") as handle:
    rows = [{k: v.strip() for k, v in row.items() if v and v.strip()} for row in csv.DictReader(handle)]

batch = talqing.email.batches.create(
    name="Guide downloads, week 36",
    task_id="5e2a7b91-0c34-4d6f-8a12-b93f5c7e2d61",
    integration_id="a41f6c2d-8b17-4e93-9d05-2c7e6f31b840",
    from_email="priya@yourdomain.com",
    from_name="Priya at Northwind",
    reply_to="priya@yourdomain.com",
    body_format="text",
    field_map={"to": "email", "subject": "subject_line", "body": "email_body"},
    recipients=[{"input": row} for row in rows],
    timezone="Asia/Kolkata",
    window={"start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5]},
    draft_concurrency=5,
)

Drafting starts immediately and runs at any hour; window applies to sending. draft_concurrency (1–10, default 5) is how many rows draft at once.
To have the task find the address too, add an output field such as work_email and map "to": "work_email".
Refused at create, in one 400: a mapped name that is neither a column nor an output field, a mapped output that is not a string, a CSV header that collides with an output name, a required task variable with no column or default, an unverified from_email. See creating a batch.
A column that exists but is blank on some rows passes create; those rows fail at drafting with invalid_input, without running the model.

In the dashboard this is Email → Outbound → New batch.

6. Review and send

When drafting finishes, the batch status is drafted (Ready to review). Nothing has been sent. List the drafts; not_ready_reason says why a row cannot go yet:

curl -sS "https://api.talqing.com/v1/email/batches/$BATCH_ID/recipients?status=draft" \
  -H "Authorization: Bearer $TALQING_API_KEY"

Fix a cell with an override. Overrides are stored separately from what the task wrote and always win, including over a later redraft:

curl -sS -X PATCH "https://api.talqing.com/v1/email/batches/$BATCH_ID/recipients/$RECIPIENT_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overrides": {"subject_line": "Your second warehouse"}}'

Then create a send. scope: "all" takes every draft; scope: "selected" with recipient_ids takes only those rows.

curl -sS -X POST "https://api.talqing.com/v1/email/batches/$BATCH_ID/sends" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": "all", "send_gap_seconds": 45, "send_daily_cap": {"kind": "fixed", "limit": 100}}'

send_daily_cap (default 200 a day per batch) is what protects a new sending domain’s reputation. Raise it gradually, or use a ramp — see creating a batch. At 45 seconds apart and 100 a day, 1,000 rows take ten sending days.

A send can be paused, resumed or cancelled; cancelling returns every unsent row to draft. See reviewing and sending.

Test it

Run the task by hand on a domain you know. If specific_detail is generic, every row will be.
Create a two-row batch with your own addresses and watch scheduled → drafting → drafted.
Blank one row’s domain before upload; it should fail alone with invalid_input.
Send both to yourself and check line breaks, from_name and reply-to.

What to know before scaling

Republishing the task mid-batch changes later rows. drafted_versions on the batch shows the split; POST /v1/email/batches/{batch_id}/redraft with selection: "stale_version" reruns the older rows, at the cost of another task run each.
Dedup is per batch. One address is mailed at most once per batch; the same person on two batches gets two emails. Suppression of bounces and complaints is Resend’s.
Sent means Resend accepted it. Delivery, bounces and complaints are in the Resend dashboard.
A batch stops itself after ten consecutive drafting failures or one configuration failure. See monitoring.

Reviewing and sending

Skipping rows, redrafting and the send in full.

Task tools and MCPs

What a task can reach while it works.

Get started

Build

Guides

Research and outreach

1. Connect Tavily and narrow its tools

2. Write the task

3. Run it once and read the result

4. Connect Resend

5. Create the batch

6. Review and send

Test it

What to know before scaling

Next

Reviewing and sending

Task tools and MCPs

​1. Connect Tavily and narrow its tools

​2. Write the task

​3. Run it once and read the result

​4. Connect Resend

​5. Create the batch

​6. Review and send

​Test it

​What to know before scaling

​Next

Reviewing and sending

Task tools and MCPs

1. Connect Tavily and narrow its tools

2. Write the task

3. Run it once and read the result

4. Connect Resend

5. Create the batch

6. Review and send

Test it

What to know before scaling

Next