Monitoring

GET /v1/email/batches/{batch_id} returns a batch’s drafting status, row counts, what it is waiting for and what drafting has cost. Each send has its own status, which you read with GET /v1/email/batches/{batch_id}/sends/{send_id}. A batch and its sends fail and stop independently: stopping a batch never stops a send, and a send failing never stops the batch.

curl https://api.talqing.com/v1/email/batches/7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57 \
  -H "Authorization: Bearer $TALQING_API_KEY"

const batch = await talqing.email.batches.get({
  batch_id: "7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57",
});
console.log(batch.status, batch.counts, batch.next_draft_reason, batch.failure_reason);

batch = talqing.email.batches.get("7c1d94a3-58b2-4e60-9f13-0a6d2c8e4b57")
print(batch["status"], batch["counts"], batch["next_draft_reason"], batch["failure_reason"])

{
  "status": "drafting",
  "counts": {
    "total": 4200, "pending": 3702, "drafting": 5, "draft": 468, "draft_failed": 6,
    "skipped": 12, "queued": 0, "sending": 0, "sent": 7, "send_failed": 0, "canceled": 0
  },
  "skips": { "operator": 2, "duplicate_recipient": 0, "unfillable": 10 },
  "draft_failures": [{ "reason": "subject is empty (subject_line)", "count": 6 }],
  "next_draft_at": null,
  "next_draft_reason": null,
  "drafted_versions": [{ "version": 3, "count": 96 }, { "version": 2, "count": 379 }],
  "published_task_version": 3,
  "stale_redraftable": 379,
  "stale_sent": 0,
  "sent_today": 7,
  "send_daily_cap_today": 200,
  "failure_reason": null,
  "provider_cost": 11.4832
}

Field	Meaning
`counts`	Rows per row status, plus `total`. `draft` counts drafts that no live send covers. `queued` counts drafts that one does.
`skips`	`counts.skipped` broken down by reason. `unfillable` rows are left out of progress.
`draft_failures`	Up to five `last_error` values among `draft_failed` rows, most common first.
`drafted_versions`	Rows per task version that wrote them, newest first, including rows already sent.
`stale_redraftable` / `stale_sent`	Rows from older versions that a `stale_version` redraft would rewrite, and how many of those older-version rows are already sent.
`sent_today` / `send_daily_cap_today`	Emails this batch has sent today in its local timezone, and today’s limit. The limit is shared by all of the batch’s sends.
`failure_reason`	Why the batch paused or failed.
`provider_cost`	What drafting has cost so far. `null` until the first task run reports a cost.
`input_columns` / `output_columns`	Your CSV headers, and the fields the task declares (read live).
`started_at` / `drafted_at`	When drafting started, and when the last row finished drafting.

Batch statuses

The status filter on GET /v1/email/batches accepts these values.

API	Dashboard	Meaning
`scheduled`	Scheduled	Waiting for `start_at`.
`drafting`	Drafting	Running the task over rows.
`paused`	Paused	Paused by a person, or by the batch itself after repeated failures (then `failure_reason` is set). Resume continues from where it stopped.
`drafted`	Ready to review	Every row added so far has finished drafting. This says nothing about sending. A batch can stay `drafted` with nothing sent.
`canceled`	Canceled	Drafting has ended permanently. Existing drafts can still be sent.
`failed`	Stopped	Drafting stopped and retrying cannot help. See `failure_reason`.

Verb	Allowed from	Effect
`POST .../pause`	`scheduled`, `drafting`, `drafted`	Stops claiming rows. Runs already in flight finish. Rows added while paused wait.
`POST .../resume`	`paused`	Continues, and clears `failure_reason`. Goes back to `scheduled` if `start_at` is still in the future.
`POST .../cancel`	`scheduled`, `drafting`, `paused`	Ends drafting. Undrafted rows read `canceled`. Drafts stay sendable.

Other transitions return 409. None of these verbs affects a send. A send scheduled for Monday still goes out after the batch is cancelled.

Why nothing is happening

next_draft_at and next_draft_reason on the batch, and next_send_at and next_send_reason on a send, say what each is waiting for. They are null while it is working, and while it is paused or finished.

Reason	On	Waiting for
`start`	batch, send	`start_at`
`retry`	batch, send	Every remaining row is in its retry backoff.
`window`	send	The next opening of `window`.
`daily_cap`	send	The next local midnight. The cap is shared across the batch.
`gap`	send	`send_gap_seconds` between emails. Only shown when the wait is a minute or more.
`drafting`	send	Rows the send covers are still drafting. `next_send_at` is `null`.

Policy edits such as raising the cap, removing the window or shortening the gap take effect within five minutes, with no restart.

When a batch stops itself

Trigger	Result
10 consecutive row drafting failures (rolling; any success resets the count)	Batch becomes `paused`, `failure_reason` is set, and `email_batch.paused` fires. Fix the cause, then resume.
One `configuration` failure, such as a deleted tool, a missing provider key or a broken integration credential	Batch becomes `failed`.
The creator left the workspace or is no longer ADMIN/EDITOR (checked when drafting starts or restarts), the task was deleted, or a task publish broke the field map	Batch becomes `failed`.

invalid_input failures and runs that produced nothing sendable do not count toward the ten.

Why a row failed

During drafting, last_error reads {error_type}: {message}, for example invalid_input: this run supplied no value for required input(s): company.

`error_type`	Retried up to `draft_attempts`?
`provider_error`, `timeout`, `platform`	Yes, `draft_retry_after_minutes` apart
`canceled` (a deploy stopped the worker)	Yes, without using an attempt
`invalid_input`	No. Fill the cell and redraft.
`no_output`, `step_limit`	No. A rerun gives the same result.
`configuration`	No, and the batch fails

A row whose run succeeded but produced nothing sendable has a plain last_error such as to is empty (work_email). The message the worker drafting this row stopped before it finished means the row went back to pending without using an attempt. Exhausted rows are draft_failed until you edit or redraft them. See task errors for each error_type.

Send failures

For a failed send, last_error holds Resend’s own message.

Class	Examples	Result
Rate limit	HTTP 429	Row retries at Resend’s `retry-after`. It uses no attempt and does not count toward the breaker.
Transient	5xx, network errors, anything unrecognised	Row goes back to `queued` and retries after `send_retry_after_minutes`, up to `send_attempts`, then becomes `send_failed`. Counts toward the breaker.
Row	Malformed address, payload refused	Row becomes `send_failed` and the send continues. Does not count toward the breaker.
Account	Revoked key, unverified domain, exhausted quota	The send becomes `failed` immediately. Its unsent rows go back to `draft`. Fix the cause and create a new send.

10 consecutive transient failures pause the send (paused, with failure_reason set, and email_batch.send.paused fires). Its rows stay covered, and resume continues from where it stopped. A send also becomes failed if the integration is disabled or deleted, or if its creator has left the workspace or lost the ADMIN/EDITOR role.

Webhooks

Event	Fires when
`email_batch.started`	Drafting claims its first row.
`email_batch.drafted`	The last row finishes drafting. It fires again after rows added later finish.
`email_batch.paused`	Drafting paused itself after 10 consecutive failures.
`email_batch.failed`	Drafting stopped for good.
`email_batch.send.started`	A send begins working through its rows.
`email_batch.send.completed`	Every row the send covers has been sent or has failed. It fires again if added rows reopen an `all` send.
`email_batch.send.paused`	A send paused itself after 10 consecutive provider failures.
`email_batch.send.failed`	A send stopped on an account-level failure.

The email_batch.* events carry the batch. The email_batch.send.* events carry the send. See webhooks for the envelope and signatures.

Cost

provider_cost is the sum of every row’s task-run model spend on your provider keys. Talqing charges no platform fee on email batches. Per-call charges from the task’s tools and MCP servers appear only on those vendors’ bills.

Task spend is not shown in the Observability charts, and nothing caps it. Every drafted row is billed whether or not it is ever sent.

Deleting a batch

DELETE /v1/email/batches/{batch_id} permanently removes the batch, its rows and its sends. That includes the record of what was sent to whom, so export the CSV first if you might need it. Only a drafted, canceled or failed batch with no live send can be deleted. Otherwise the request returns 409.

Create, review and send

Editing rows, redrafting, and creating a send.

Webhooks

Signatures, retries and delivery records.

Get started

Build

Guides

Batch statuses

Why nothing is happening

When a batch stops itself

Why a row failed

Send failures

Webhooks

Cost

Deleting a batch

Next

Create, review and send

Webhooks

​Batch statuses

​Why nothing is happening

​When a batch stops itself

​Why a row failed

​Send failures

​Webhooks

​Cost

​Deleting a batch

​Next

Create, review and send

Webhooks

Batch statuses

Why nothing is happening

When a batch stops itself

Why a row failed

Send failures

Webhooks

Cost

Deleting a batch

Next