Generate Batch (multiple leads)

Api ReferenceUpdated February 18, 2025

Generate Batch (multiple leads)

Generate personalized cold email sequences for multiple leads in one request. The API accepts the batch and returns immediately with a list_id. Processing runs asynchronously; you poll the list status and then export results when completed.

POST /api/v1/campaigns/:id/generate-batch

Path parameters

Parameter	Type	Description
`id`	string (UUID)	Campaign ID (from GET /api/v1/campaigns).

Headers

Header	Required	Description
`Authorization` or `X-API-Key`	Yes	API key.
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`leads`	array	Yes	Array of lead objects (at least one). Each lead must include a valid `email`.
`leads[].name`	string	No	Full name.
`leads[].title`	string	No	Job title.
`leads[].company`	string	No	Company name.
`leads[].email`	string	Yes	Email (required; used for mapping and export).
`leads[].linkedin_url`	string	No	LinkedIn profile URL.
`leads[].company_website`	string	No	Company website.
`options`	object	No	Same as single-lead: `list_name`, `email_count`, `email_signature`, `campaign_angle`, `approved_ctas`.

Example request

curl -X POST "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID/generate-batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "name": "Jane Doe", "title": "VP Marketing", "company": "Acme Inc", "email": "jane@acme.com" },
      { "name": "John Smith", "title": "CTO", "company": "Beta Co", "email": "john@beta.co" }
    ],
    "options": {
      "list_name": "API Batch Q1",
      "email_count": 3
    }
  }'

Response (202 Accepted)

The request returns immediately. Processing continues in the background.

{
  "list_id": "uuid-of-email_sequences-row",
  "status": "processing",
  "message": "Batch accepted. Processing will continue in the background. Poll list status or open in the UI."
}

The response may also include sequence_id (deprecated); use list_id only.

Field	Type	Description
`list_id`	string (UUID)	Use this to poll `GET /api/v1/lists/:list_id` and to export with `GET /api/v1/lists/:list_id/export`.
`status`	string	`"processing"`.
`message`	string	Human-readable confirmation.

Next steps

Poll GET /api/v1/lists/:list_id until processing_status is completed or failed.
When completed, call GET /api/v1/lists/:list_id/export?format=csv or ?format=json to download results.

See Lists for list status and export details.

Error responses

Status	Error	Description
400	BAD_REQUEST	Invalid JSON, missing `leads`, or a lead missing/invalid `email`.
401	UNAUTHORIZED	Missing or invalid API key.
402	INSUFFICIENT_CREDITS	Not enough credits for this many leads.
403	FORBIDDEN	Campaign not in this workspace.
404	NOT_FOUND	Campaign not found.
429	WORKSPACE_LIMIT	Too many concurrent batch jobs; try again later.
500	INTERNAL_ERROR	Failed to enqueue or create list.

Error body: { "error": "CODE", "message": "..." } (and optionally detail).