Generate (single lead)

ReferenceUpdated June 14, 2026

Generate (single lead)

Generate a personalized cold email sequence for one lead. This is a synchronous request: the response is returned when generation is done, which can take 3–10 minutes. Use a long client timeout (at least 300 seconds, preferably 600).

POST /api/v1/campaigns/:id/generate · scope campaigns:write

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
`lead`	object	Yes	Lead data for personalization.
`lead.name`	string	No	Full name.
`lead.title`	string	No	Job title.
`lead.company`	string	No	Company name.
`lead.email`	string	Yes	Email (required; used for mapping and exports).
`lead.linkedin_url`	string	No	LinkedIn profile URL.
`lead.company_website`	string	No	Company website.
`options`	object	Yes	Generation config. `email_count` and a signature are required (see below).

Options

Option	Type	Required	Description
`email_count`	number	Yes	Number of emails in the sequence. Integer 1–4.
`email_signature`	string	Yes*	Sender signature, inline. Required unless `signature_id` is provided. Multi-line: use `\n` between lines, e.g. `"Jane Doe\nAcme Inc \| VP Marketing\n123 Main St, Springfield, IL 62701"`. Each line renders on its own line.
`signature_id`	string (UUID)	Yes*	ID of a saved signature (from GET /api/v1/signatures) to use instead of `email_signature`. Provide exactly one of the two.
`list_name`	string	No	Display name for the list in the UI (default: derived from lead).
`enrichment_enabled`	boolean	No	Enable lead enrichment via web research (adds persona description, company data, industry, etc.). Costs 1 extra credit per lead (2 total). Default: `false`. Requires the lead to include at least one of `company`, `linkedin_url`, or `company_website`.
`additional_details`	string	No	Free-text campaign context passed to the writer ("Added Campaign Details") — angle, constraints, or instructions that override defaults.
`approved_ctas`	string or string[]	No	CTAs to use (e.g. `"Direct Meeting CTA, Lead Magnet CTA"` or array). Defaults to `Question CTA, Lead Magnet CTA, Direct Meeting CTA`.

* 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. The signature is required so the writer never fabricates sender details.

Example request

curl -X POST "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead": {
      "name": "Jane Doe",
      "title": "VP Marketing",
      "company": "Acme Inc",
      "email": "jane@acme.com",
      "company_website": "https://acme.com"
    },
    "options": {
      "email_count": 3,
      "email_signature": "Sam Rivera\nMachFive | Founder\n500 Market St, San Francisco, CA 94105",
      "list_name": "API: jane@acme.com",
      "enrichment_enabled": true
    }
  }'

Response (200 OK)

{
  "lead_id": "lead_xyz789",
  "list_id": "uuid-of-email_sequences-row",
  "sequence": [
    { "step": 1, "subject": "...", "body": "..." },
    { "step": 2, "subject": "...", "body": "..." },
    { "step": 3, "subject": "...", "body": "..." }
  ],
  "credits_remaining": 94
}

Field	Type	Description
`lead_id`	string	Internal lead identifier.
`list_id`	string (UUID)	List/sequence row ID (for status or export if needed).
`sequence`	array	Generated emails: `step`, `subject`, `body` per step.
`credits_remaining`	number	Credits left in the workspace after this request.

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

Error responses

Status	Error	Description
400	BAD_REQUEST	Invalid JSON; missing `lead`; missing/invalid `lead.email`; `email_count` missing or not 1–4; no signature (neither `email_signature` nor `signature_id`) or both provided; `enrichment_enabled` with a lead missing all of company/linkedin_url/company_website; or campaign setup is incomplete (no knowledge base yet and value propositions not completed).
401	UNAUTHORIZED	Missing or invalid API key.
402	INSUFFICIENT_CREDITS	Not enough credits (1 per lead, or 2 with enrichment enabled). `detail` includes `{ required, available, payg_enabled, pct_of_cap }`.
403	FORBIDDEN	Campaign not in this workspace.
404	NOT_FOUND	Campaign not found, or `signature_id` not found in this workspace.
429	RATE_LIMITED	Per-key rate limit exceeded; honor `Retry-After`.
500	INTERNAL_ERROR	Generation failed.

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

Note: This endpoint does not support Idempotency-Key. A retried request generates again and charges again. See Conventions → Idempotency for the endpoints that do.

Related guides