Getting Started

Follow these steps to start using the MachFive API.

1. Create an API key

API keys are created in the MachFive app and are scoped to a workspace.

1. Log in at app.machfive.io.
2. Open Settings (or Workspace → API Keys).
3. Go to the API Keys section.
4. Click Create API Key.
5. Enter a name (e.g. "Production" or "OpenClaw") and create the key.
6. Copy the key and store it securely. It is shown only once and cannot be retrieved later.

Key format: mf_live_ followed by 32 hexadecimal characters (e.g. mf_live_a1b2c3d4e5f60718293a4b5c6d7e8f90).

2. Base URL and headers

• Base URL: https://app.machfive.io
• Auth: Send your API key on every request (see Authentication).

Example:

curl -X GET "https://app.machfive.io/api/v1/campaigns" \
  -H "Authorization: Bearer mf_live_YOUR_KEY_HERE"

3. First request: list campaigns

To see which campaigns you can use for generation:

curl -X GET "https://app.machfive.io/api/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "campaigns": [
    { "id": "uuid", "name": "Q1 Outbound", "created_at": "2025-01-15T12:00:00.000Z" }
  ],
  "has_more": false,
  "total": 1
}

Use a campaign id in the generate or generate-batch endpoints.

4. Generate for one lead (sync)

To generate a sequence for a single lead (takes 3–10 minutes):

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"
    },
    "options": {
      "email_count": 3,
      "email_signature": "Sam Rivera\nMachFive | CXO\n500 Market St, San Francisco, CA 94105"
    }
  }'

options is required: email_count (integer 1–4) and a signature (inline email_signature with \n line breaks, or a saved signature_id from GET /api/v1/signatures). Without them the request returns 400. See Generate for all options.

Important: Use a timeout of at least 300 seconds (5 minutes) or 600 seconds (10 minutes). Shorter timeouts will cut off the response.

5. Generate for multiple leads (async)

To process many leads without waiting:

1. POST to POST /api/v1/campaigns/:id/generate-batch with { "leads": [ {...}, ... ], "options": { ... } }.
2. You get 202 Accepted with list_id.
3. Poll GET /api/v1/lists/:list_id until processing_status is completed (or failed).
4. Export results with GET /api/v1/lists/:list_id/export?format=csv or ?format=json.

See Generate Batch and Lists for details.

6. Conventions

All endpoints share a common set of behaviors — request IDs, pagination, idempotency, and async-job polling. These are documented once in Conventions.