POST
Create Email Batch

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Each email is written either by an agent task (task_id + field_map) or by a fixed template filled from the row's columns.

​
from_email
string
required

The default sending address. Its domain must be verified on that Resend account; a send may override this for its own rows alone.

​
integration_id
string<uuid>
required

A connected Resend account.

​
name
string
required
Required string length: 1 - 200
​
recipients
EmailRecipientInput · object[]
required
Required array length: 1 - 10000 elements
​
timezone
string
required
​
body_format
enum<string>
default:text
Available options:
text,
html
​
draft_attempts
integer
default:1
Required range: 1 <= x <= 5
​
draft_concurrency
integer
default:5
Required range: 1 <= x <= 10
​
draft_gap_seconds
integer
default:0

Minimum seconds between STARTING two rows. 0 starts each as a slot frees; raise it when the task calls something that rate-limits.

Required range: 0 <= x <= 3600
​
draft_retry_after_minutes
integer
default:30
Required range: 5 <= x <= 1440
​
field_map
FieldMap · object | null

With task_id only.

​
from_name
string | null
Maximum string length: 200
​
reply_to
string | null
​
send_attempts
integer
default:3
Required range: 1 <= x <= 5
​
send_daily_cap
FixedDailyCap · object

The same limit every day.

​
send_gap_seconds
integer
default:1

Minimum seconds between STARTING two emails. 60 means one a minute.

Required range: 1 <= x <= 3600
​
send_retry_after_minutes
integer
default:30
Required range: 5 <= x <= 1440
​
start_at
string<date-time> | null
​
task_id
string<uuid> | null

The agent task that drafts each row.

​
template
EmailTemplate · object | null

Instead of a task: no drafting, every row is ready at once.

​
window
TimeWindow · object | null

When email may LEAVE. Inherited by every send this batch creates.

Response

Successful Response

​
body_format
enum<string>
required
Available options:
text,
html
​
counts
EmailBatchCounts · object
required

Rows by the status a reader sees. draft is drafts no live send covers yet; queued is drafts one does.

​
created_at
string<date-time>
required
​
draft_attempts
integer
required
​
draft_concurrency
integer
required
​
draft_failures
DraftFailure · object[]
required
​
draft_gap_seconds
integer
required
​
draft_retry_after_minutes
integer
required
​
drafted_at
string<date-time> | null
required
​
drafted_versions
DraftedVersion · object[]
required
​
failure_reason
string | null
required
​
field_map
FieldMap · object | null
required

Which column in the merged space carries each of the three sent fields.

A value may name a CSV header or an output field of the task — that is the whole point of the merged space, and it is what makes "the CSV has emails" and "feed it a phone number and let the task find the email" the same feature.

​
from_email
string
required
​
from_name
string | null
required
​
id
string<uuid>
required
​
input_columns
string[]
required
​
integration_id
string<uuid> | null
required
​
integration_name
string | null
required
​
name
string
required
​
next_draft_at
string<date-time> | null
required
​
next_draft_reason
enum<string> | null
required
Available options:
start,
retry
​
output_columns
string[]
required
​
provider_cost
number | null
required
​
published_task_version
integer | null
required
​
reply_to
string | null
required
​
send_attempts
integer
required
​
send_daily_cap
FixedDailyCap · object
required

The same limit every day.

​
send_daily_cap_today
integer | null
required
​
send_gap_seconds
integer
required
​
send_retry_after_minutes
integer
required
​
sent_today
integer
required
​
skips
EmailBatchSkips · object
required

counts.skipped, by who decided it.

​
stale_redraftable
integer
required
​
stale_sent
integer
required
​
start_at
string<date-time> | null
required
​
started_at
string<date-time> | null
required
​
status
enum<string>
required
Available options:
scheduled,
drafting,
paused,
drafted,
canceled,
failed
​
task_id
string<uuid> | null
required
​
task_name
string | null
required
​
template
EmailTemplate · object | null
required

A fixed email, filled per row: {{column}} in subject or body takes that row's cell.

​
timezone
string
required
​
window
TimeWindow · object | null
required

The hours a list may run in, on the list's own clock.

Shared rather than duplicated, for the same reason window_state is: a call batch and an email send run store the same three values under the same names and must not each get their own copy of the rules. The field that carries one is named for what it gates — calling_window on a campaign, window on an email batch and its runs.

A window that crosses midnight (21:00-06:00) is valid and means exactly what an evening consumer-calling window means: the day check applies to the start side, so 21:00-06:00 on days: [5] runs Friday 21:00 through Saturday 06:00.