Generate (single lead)

Api ReferenceUpdated February 18, 2025

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

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	No	List/generation options (see below).

Options (optional)

Option	Type	Description
`list_name`	string	Display name for the list in the UI (default: derived from lead).
`email_count`	number	Number of emails in sequence (1–5; default from campaign or 3).
`email_signature`	string	Signature appended to generated emails.
`campaign_angle`	string	Context/angle for personalization.
`approved_ctas`	string or string[]	CTAs to use (e.g. `"Direct Meeting CTA, Lead Magnet CTA"` or array).

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": {
      "list_name": "API: jane@acme.com",
      "email_count": 3
    }
  }'

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`, or campaign has no vector store.
401	UNAUTHORIZED	Missing or invalid API key.
402	INSUFFICIENT_CREDITS	Not enough credits; message includes upgrade guidance.
403	FORBIDDEN	Campaign not in this workspace.
404	NOT_FOUND	Campaign not found.
500	INTERNAL_ERROR	Generation failed.

Error body shape: { "error": "CODE", "message": "Human-readable message" }.