Create, review and send

POST /v1/email/batches uploads a list, the agent task that drafts each row, a connected Resend integration and a field_map. The batch is created scheduled and starts drafting. Nothing is emailed until you POST /v1/email/batches/{batch_id}/sends. Before you start, read Email outbound for the acceptable-use rule and Resend setup.

Create a batch

curl -X POST https://api.talqing.com/v1/email/batches \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding follow-up, week 34",
    "task_id": "5e2a7b91-0c34-4d6f-8a12-b93f5c7e2d61",
    "integration_id": "a41f6c2d-8b17-4e93-9d05-2c7e6f31b840",
    "from_email": "priya@yourdomain.com",
    "from_name": "Priya at Northwind",
    "field_map": { "to": "email", "subject": "subject_line", "body": "email_body" },
    "recipients": [
      { "input": { "email": "asha@example.com", "company": "Asha Textiles" } },
      { "input": { "email": "ravi@example.org", "company": "Ravi Foods" } }
    ],
    "timezone": "Asia/Kolkata",
    "window": { "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] }
  }'

const batch = await talqing.email.batches.create({
  createEmailBatchRequest: {
    name: "Onboarding follow-up, week 34",
    task_id: "5e2a7b91-0c34-4d6f-8a12-b93f5c7e2d61",
    integration_id: "a41f6c2d-8b17-4e93-9d05-2c7e6f31b840",
    from_email: "priya@yourdomain.com",
    from_name: "Priya at Northwind",
    field_map: { to: "email", subject: "subject_line", body: "email_body" },
    recipients: [
      { input: { email: "asha@example.com", company: "Asha Textiles" } },
      { input: { email: "ravi@example.org", company: "Ravi Foods" } },
    ],
    timezone: "Asia/Kolkata",
    window: { start: "09:00", end: "18:00", days: [1, 2, 3, 4, 5] },
  },
});
console.log(batch.id, batch.status, batch.skips.unfillable);

batch = talqing.email.batches.create(
    name="Onboarding follow-up, week 34",
    task_id="5e2a7b91-0c34-4d6f-8a12-b93f5c7e2d61",
    integration_id="a41f6c2d-8b17-4e93-9d05-2c7e6f31b840",
    from_email="priya@yourdomain.com",
    from_name="Priya at Northwind",
    field_map={"to": "email", "subject": "subject_line", "body": "email_body"},
    recipients=[
        {"input": {"email": "asha@example.com", "company": "Asha Textiles"}},
        {"input": {"email": "ravi@example.org", "company": "Ravi Foods"}},
    ],
    timezone="Asia/Kolkata",
    window={"start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5]},
)
print(batch["id"], batch["status"], batch["skips"]["unfillable"])

recipients[].input is one CSV row keyed by header. Values are strings. Leave out empty cells instead of sending "". In the dashboard, Email → Outbound → New batch parses a CSV in the browser and posts the same request. The dashboard’s confirm dialog states how many task runs you are about to pay for.

The column space and `field_map`

Each row has one flat set of columns, merged in this order. A later layer wins:

Layer	Source	Written
`input`	Your uploaded row	At create
`output`	The task’s typed result	When the row drafts
`overrides`	Cells a person edited	Any time before the row is sent

The merged result is the row’s columns. field_map.to, .subject and .body can each name either a CSV header or a task output field. For example, a list that already has addresses maps to to a CSV column such as email. A list of phone numbers maps to to an output field such as work_email, which the task looks up with its tools. Output fields you do not map are kept on the row and shown in review, but they are never sent. Requirements on the task:

Mapped output fields must be string. A boolean, integer or number output field cannot be mapped.
Each row’s uploaded columns, plus edits to those columns, become the task’s {{vars.*}}. All of them are passed, not only the ones the task declares. See inputs and output.
The task must be published. Drafting always uses the current published version. Publishing or rolling back a version that would break a live batch’s field map is refused. Deleting the task is refused while a batch using it is scheduled, drafting or paused.

A row is sendable when all three mapped names resolve to non-empty strings, to parses as an email address, and subject has no line break. When a mapped column that the task does not write is blank or invalid, no draft could fix it. That row is skipped with skip_reason: "unfillable" at upload, is never drafted, and costs nothing. skips.unfillable on the response counts these rows.

What is refused at create

Every problem is returned at once in one 400:

{
  "detail": {
    "message": "invalid email batch",
    "errors": [
      "field_map.body names 'message', which is neither a column in the list nor something the task produces",
      "the task requires a 'company' variable and the list has no such column - add it, give the variable a default, or make it optional"
    ]
  }
}

A mapped name that is neither a CSV header nor an output field of the published task, or that maps to a non-string output field.
A CSV header that is also a task output field name. Rename one of them.
A required task variable with no matching column and no default.
A header that is not a valid variable name. Headers must use letters, digits and underscores and start with a letter or underscore.
A from_email whose domain is not verified on the account, or a from_email or reply_to that is not an address.
An integration that is missing, is not Resend, or is not active. A task that is missing or has never been published.
start_at in the past or more than 90 days ahead. Zero rows, or more than 10,000 rows in one request. Add more rows with add recipients.

The required-variable check looks at headers, not cells. A row whose required column is blank fails at drafting with invalid_input. Only that row fails, and no tokens are spent. Fill the cell and redraft it.

Batch fields

Field	Default	Meaning
`name`	required	1–200 characters.
`body_format`	`text`	`text` or `html`. Use `html` only if the task writes HTML.
`timezone`	required	IANA zone. It sets the clock for `window`, the daily cap’s day boundary and the times shown on the batch page.
`start_at`	`null`	When drafting starts. `null` starts it immediately. You can change it only while the batch is `scheduled`.
`window`	`null`	`{start, end, days}`: when email may leave. `days` are ISO weekdays (1 = Monday). A window may cross midnight. `start` must not equal `end`. Drafting runs at any hour.
`draft_concurrency`	`5`	1–10 rows drafting at once. This is the main limit on drafting speed.
`draft_attempts`	`1`	1–5. Only `provider_error`, `timeout` and `platform` failures are retried.
`draft_retry_after_minutes`	`30`	5–1440.
`draft_gap_seconds`	`0`	0–3600 seconds between starting two rows. Raise it if a tool the task calls is rate-limited.
`send_attempts`	`3`	1–5 attempts per row for transient provider failures.
`send_retry_after_minutes`	`30`	5–1440.
`send_gap_seconds`	`1`	1–3600 seconds between two emails of this batch, across all its sends. Sending is serial.
`send_daily_cap`	`{"kind":"fixed","limit":200}`	Emails per local day for the whole batch, across all its sends. `null` means uncapped.

The four send_* fields are defaults. Each send copies them when it is created. PATCH /v1/email/batches/{batch_id} changes them for the next send. Use PATCH .../sends/{send_id} to change a send that already exists. A running batch or send applies a policy change within five minutes.

Warming up a new domain

send_daily_cap is either {"kind": "fixed", "limit": 200} (limit ≥ 1) or a ramp:

{ "send_daily_cap": { "kind": "ramp", "start": 10, "end": 50, "step": 1, "interval_days": 1 } }

A ramp starts at start emails a day and rises by step every interval_days (1–30) until it reaches end (end > start). It counts only days the batch actually sent, so weekends, closed windows and pauses do not advance it. send_daily_cap_today shows the limit in force today. Editing a ramp keeps its progress unless you change start. Each batch ramps separately, so two batches on the same domain together send the sum of their caps.

send_daily_cap is your main protection for a domain’s reputation. A new domain that sends thousands of emails in an afternoon can lose inbox placement, and no review step reverses that. Raise the cap gradually.

Review the drafts

GET /v1/email/batches/{batch_id}/recipients?status=draft&limit=50 returns rows in upload order (limit up to 200, with offset).

Field	Meaning
`columns`	The merged column space that `field_map` resolves against.
`input`, `output`, `overrides`	The three layers, separately. `output` is `null` until the row drafts.
`status`	See row statuses.
`not_ready_reason`	Why the row cannot be sent, such as `subject is empty (subject_line)` or `'ravi at example.org' is not an email address`. It is always `null` on a `draft`.
`skip_reason`	`unfillable`, `duplicate_recipient`, or `operator` (on older rows only).
`task_run_id`, `task_version`	The run that drafted the row and the task version it used.
`last_error`	Why the last attempt failed. See monitoring.
`send_run_id`, `to_email`, `sent_from`, `sent_at`, `send_attempts`	Set when a send claims the row.

A draft is always sendable. A row whose task run succeeded but produced nothing sendable, for example because no address was found, is draft_failed. The reason is in last_error, and the task output is kept so you can read what the task did find. Export CSV on the batch page in the dashboard downloads every row. It contains your columns, the output fields, status and error. Values are written raw, so a cell starting with = opens as a formula in a spreadsheet.

Edit a cell

PATCH /v1/email/batches/{batch_id}/recipients/{recipient_id} writes overrides:

curl -X PATCH \
  https://api.talqing.com/v1/email/batches/7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57/recipients/e58207f6-1c94-4d3a-b7e0-3f9c15a86d22 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "overrides": { "work_email": "asha@example.com", "subject_line": "Your Q3 order" } }'

An edit never overwrites output, and a redraft never overwrites an edit.
An empty string clears the edit and falls back to the layer below.
Editing one of your uploaded columns changes what the task receives the next time the row drafts.
The row’s status is recomputed. Filling a missing mapped cell moves draft_failed back to draft, and moves an unfillable row back to pending so it gets drafted. Clearing a mapped cell moves a row the other way. The response includes the new status.
queued rows can still be edited. Once a row is sending, sent or send_failed, an edit returns 409.

Delete rows

POST /v1/email/batches/{batch_id}/recipients/delete with {"recipient_ids": [...]} permanently removes rows that were never sent: pending, draft (including queued), draft_failed or skipped. Other rows are returned in rejected with a reason.

Redraft

POST /v1/email/batches/{batch_id}/redraft with either recipient_ids or a selection resets rows to pending. It clears output, task_run_id, attempts and last_error, and the rows draft again.

`selection`	Rows moved
`failed`	Rows whose drafting failed
`stale_version`	Rows written by a task version older than the published one. `stale_redraftable` on the batch counts them.
`not_sent`	Every row that has not been sent, including `send_failed`
`all`	The same rows as `not_sent`, and it lists `drafting`, `sending` and `sent` rows in `rejected`

Every redrafted row runs the task again and is billed again, and its previous draft is discarded. Check the count before you redraft.

Edited cells survive a redraft unless you pass clear_overrides: true. unfillable rows are never redrafted. Redrafting moves a drafted or failed batch back to drafting. A paused batch stays paused. A canceled batch returns 409. A typical way to improve drafts mid-batch: pause the send, publish a better task, redraft stale_version, then resume the send. The send picks up each new draft as it lands.

Send

A send emails real people. A sent email cannot be recalled. You can pause or cancel a send before it finishes.

curl -X POST https://api.talqing.com/v1/email/batches/7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57/sends \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "recipient_ids": ["e58207f6-1c94-4d3a-b7e0-3f9c15a86d22", "b90f4c17-2a63-4d85-8e10-5c7b9a2f6a31"],
    "start_at": "2026-10-19T03:30:00Z",
    "send_gap_seconds": 45,
    "send_daily_cap": { "kind": "fixed", "limit": 150 }
  }'

const { send, rejected } = await talqing.email.batches.sends.create({
  batch_id: "7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57",
  createEmailSendRequest: {
    scope: "selected",
    recipient_ids: ["e58207f6-1c94-4d3a-b7e0-3f9c15a86d22", "b90f4c17-2a63-4d85-8e10-5c7b9a2f6a31"],
    start_at: "2026-10-19T03:30:00Z",
    send_gap_seconds: 45,
    send_daily_cap: { kind: "fixed", limit: 150 },
  },
});
console.log(send.id, send.status, send.next_send_at, rejected);

res = talqing.email.batches.sends.create(
    "7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57",
    scope="selected",
    recipient_ids=["e58207f6-1c94-4d3a-b7e0-3f9c15a86d22", "b90f4c17-2a63-4d85-8e10-5c7b9a2f6a31"],
    start_at="2026-10-19T03:30:00Z",
    send_gap_seconds=45,
    send_daily_cap={"kind": "fixed", "limit": 150},
)
print(res["send"]["id"], res["send"]["status"], res["rejected"])

`scope`	Covers
`selected`	Exactly `recipient_ids`. Rows that cannot go (not in the batch, not a `draft`, held by another live send, or not sendable) come back in `rejected` and stay drafts. If none of the rows can go, the request returns 400. A duplicated id also returns 400.
`all`	Every row of the batch as it reaches `draft`, including rows not drafted yet. Drafts go out without anyone reading them. The send waits while drafting runs and finishes when there is nothing left to draft or send. Takes no `recipient_ids`.

Several selected sends can be live at once, but a row belongs to only one. An all send cannot be live alongside any other send of the same batch. That conflict returns 409. Send fields. Any field you omit is taken from the batch:

start_at: at most 90 days ahead.
timezone, window: an explicit null window means any hour.
send_gap_seconds, send_attempts, send_retry_after_minutes, send_daily_cap: an explicit null cap means uncapped.
from_email, from_name, reply_to: apply to this send only. An overridden from_email is checked against your verified domains.

PATCH /v1/email/batches/{batch_id}/sends/{send_id} changes the pacing, window and cap, and start_at before the send begins. It never changes the sender or scope. To change which rows a send covers, cancel it and create another.

Verb	Allowed from	Effect
`POST .../sends/{send_id}/pause`	`scheduled`, `sending`	Stops before the next email. Rows stay `queued` and you can still edit, delete or redraft them.
`POST .../sends/{send_id}/resume`	`paused`	Continues, and clears `failure_reason`.
`POST .../sends/{send_id}/cancel`	`scheduled`, `sending`, `paused`	Ends the send. Unsent rows go back to `draft`. A row mid-send finishes.

A send’s counts has total (null for all), queued, drafting, sending, sent, send_failed and skipped. next_send_at and next_send_reason show what the send is waiting for. See monitoring.

Work out how long a send will take before you start it. For example, 1,240 rows at 45 seconds apart is about 15 hours of sending. With a 09:00–17:00 window and a cap of 150 a day, that is nine working days.

Duplicates and resends

An address is emailed at most once per batch. The check runs when a send claims the row, because the task may be the one that found the address. A second row with the same address is skipped with skip_reason: "duplicate_recipient".
There is no deduplication across batches, and Talqing keeps no suppression list. Resend keeps one on your account.
Each email carries an idempotency key, the row’s id, which Resend honours for 24 hours. A row interrupted by a crash is resent under the same key and is not delivered twice.

Adding rows later

POST /v1/email/batches/{batch_id}/recipients appends up to 10,000 rows to any batch that is not canceled or failed. A drafted batch starts drafting again. Duplicates are dropped before drafting:

If to maps to an uploaded column, a row whose address is already in the batch is dropped.
Otherwise, a row whose uploaded cells exactly repeat another row’s is dropped.

The response has added, skipped (each entry has row_number and reason, plus recipient_id if the row was stored as unfillable), total_recipients and standing_send_id.

If the batch’s most recent send was an all send that has finished, adding rows reopens it. The new rows are then emailed without review. standing_send_id names that send. Otherwise new rows wait for you to review them.

curl -X POST https://api.talqing.com/v1/email/batches/7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57/recipients \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": [{ "input": { "email": "meera@initech.com", "company": "Initech" } }] }'

Row statuses

API	Dashboard	Meaning
`pending`	Not drafted	Waiting to draft, or waiting out a retry.
`drafting`	Drafting	The task is running for this row.
`draft`	Draft	Drafted and sendable. Only `draft` rows can be sent.
`draft_failed`	Draft failed	The task failed, or it produced nothing sendable. Fix the cells or redraft.
`skipped`	Skipped	`unfillable`, `duplicate_recipient` or `operator`.
`queued`	Queued	A `draft` that a live send covers. It is computed when read. Cancelling the send makes it `draft` again.
`sending`	Sending	The Resend call is in flight.
`sent`	Sent	Resend accepted it.
`send_failed`	Send failed	Resend refused it, or its attempts ran out. `last_error` has Resend’s message.
`canceled`	Canceled	Never drafted, on a cancelled or stopped batch. It is computed when read.

Fields locked after the first send

Once the batch has a send, or any row is sending, sent or send_failed, a PATCH to from_email, from_name, reply_to, body_format or field_map returns 400. name, timezone, window, the drafting and sending fields, and send_daily_cap stay editable. A batch can be edited only while it is scheduled, drafting, paused or drafted.

Monitoring

Statuses, counts, why a batch or send stops itself, webhooks and cost.

Research and outreach

A task that researches each lead, feeding an email batch end to end.

Get started

Build

Guides

Create, review and send

Create a batch

The column space and `field_map`

What is refused at create

Batch fields

Warming up a new domain

Review the drafts

Edit a cell

Delete rows

Redraft

Send

Duplicates and resends

Adding rows later

Row statuses

Fields locked after the first send

Next

Monitoring

Research and outreach

​Create a batch

​The column space and field_map

​What is refused at create

​Batch fields

​Warming up a new domain

​Review the drafts

​Edit a cell

​Delete rows

​Redraft

​Send

​Duplicates and resends

​Adding rows later

​Row statuses

​Fields locked after the first send

​Next

Monitoring

Research and outreach

Create a batch

The column space and `field_map`

What is refused at create

Batch fields

Warming up a new domain

Review the drafts

Edit a cell

Delete rows

Redraft

Send

Duplicates and resends

Adding rows later

Row statuses

Fields locked after the first send

Next