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 · scope campaigns:write

You can submit a batch before the build finishes. As soon as value propositions are selected, the campaign is eligible for generation — you do not need to wait for build-status overall to reach ready. Batches submitted while the build is still in progress (overall: "building") are accepted and queued; processing begins automatically once the build completes. Submitting before value propositions are selected returns 400 BAD_REQUEST (campaign setup incomplete).

Path parameters

Headers

Request body

* Exactly one of email_signature or signature_id is required (providing both is a 400).

Note: campaign_angle is a deprecated alias of additional_details, and sequence_name is a deprecated alias of list_name. Prefer the new names.

Completion notifications. When a batch finishes processing in the background, MachFive sends a "processing complete" email containing a link to the processed list. By default this goes to the workspace owner. Set options.notification_email to send it to a different address instead. (The single-lead generate endpoint returns results synchronously in the response and does not send a notification email.)

Signature format

The signature is required so the writer never fabricates sender details. Send it as a single string with \n line breaks; each line is rendered on its own line in the email. Best-practice cold-email structure:

Name
Company Name | Position
Company Address

As JSON:

"email_signature": "Jane Doe\nAcme Inc | VP Marketing\n123 Main St, Springfield, IL 62701"

To reuse a saved signature instead, omit email_signature and pass signature_id (manage saved signatures via Signatures):

"signature_id": "f3a9c2e1-..."

Enrichment requirements

When enrichment_enabled is true, every lead must include at least one research signal: company, linkedin_url, or company_website. A company value also lets the system extract the email domain and cross-reference it against the company name before researching. A lead with none of these returns a 400 (enrichment would have nothing to work with).

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": {
      "email_count": 3,
      "email_signature": "Sam Rivera\nMachFive | Founder\n500 Market St, San Francisco, CA 94105",
      "list_name": "API Batch Q1",
      "enrichment_enabled": true,
      "notification_email": "ops@yourcompany.com",
      "additional_details": "Lead with the deliverability angle; keep it under 90 words."
    }
  }'

Response (202 Accepted)

The request returns immediately. Processing continues in the background.

{
  "list_id": "uuid-of-email_sequences-row",
  "status": "processing",
  "leads_count": 2,
  "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.

Next steps

1. Poll GET /api/v1/lists/:list_id until processing_status is completed or failed.
2. 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 for download details.

Error responses

Error body: { "error": "CODE", "message": "...", "detail"?: ..., "request_id": "..." }.

Note: This endpoint does not support Idempotency-Key. A retried request enqueues a new batch. Credits are deducted on-success per completed lead. See Conventions → Idempotency for the endpoints that do.