Preview

Preview a campaign's emails against 5 synthetic leads that match its Ideal Customer Profile (ICP), using the same generation engine as a real run. This is the pre-flight step in the generation workflow: you set up your lead structure and options (the same ones you'd use for a batch run), preview the output to validate tone, structure, and personalization, then process the full CSV with Generate Batch.

Requires the campaigns:write scope.

Billing: Every call costs 5 credits. If some synthetic leads fail to generate, you are refunded for the failed leads; if all fail, you are fully refunded. The credit cost is fixed at 5 per call (there is no free first preview on the API).

Readiness: The campaign's email instructions must be built first (after saving campaign strategy). If they aren't ready yet, the request returns 409 NOT_READY — wait about a minute and retry. No credits are charged when this happens.

Generate a preview

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

Path parameters

Headers

Request body

* Exactly one of email_signature or signature_id is required (providing both is a 400). Preview uses the same required config as a real run so the output faithfully reflects what generation will produce (including the real signature). campaign_angle is a deprecated alias of additional_details.

Enrichment in preview. Set enrichment_enabled to true or false to preview the campaign with or without enriched output. Preview uses synthetic leads and simulates the enrichment columns, so no per-lead data or enrichment_mapping is required, and the cost stays a flat 5 credits.

Example request

curl -X POST "https://app.machfive.io/api/v1/campaigns/CAMPAIGN_ID/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1b8e2a-..." \
  -d '{
    "sample": {
      "headers": ["First Name", "Company Name", "Title", "Email"],
      "rows": [["Jane", "Acme Inc", "VP Marketing", "jane@acme.com"]],
      "field_mapping": { "email": "Email", "firstName": "First Name", "companyName": "Company Name" }
    },
    "options": {
      "email_count": 2,
      "email_signature": "Sam Rivera\nMachFive | Founder\n500 Market St, San Francisco, CA 94105"
    }
  }'

Response (200 OK)

{
  "preview_id": "uuid",
  "status": "success",
  "credits_charged": 5,
  "success_count": 5,
  "fail_count": 0,
  "headers": ["#", "Subject Line 1", "Email 1", "Subject Line 2", "Email 2", "First Name", "Company Name", "Title"],
  "rows": [["1", "...", "...", "...", "...", "Jane", "Acme Inc", "VP Marketing"]],
  "synthetic_leads": [ { "First Name": "Jane", "email_address": "jane@acme.com" } ],
  "generated_emails": [
    {
      "lead_index": 0,
      "lead_data": { "First Name": "Jane" },
      "emails": [ { "subject": "...", "body": "..." } ],
      "status": "success"
    }
  ]
}

Error responses