machfive

Download the generated email sequences for a COMPLETED list.

Only call this AFTER get_list_status shows processing_status = 'completed'. If the list is not yet completed, you'll get a 409 error — poll first.

Args: list_id: The list UUID to export. format: Output format — 'json' (default, structured) or 'csv' (raw CSV string). Use 'json' when the agent needs to read/process the sequences. Use 'csv' when the user wants a file to upload to their sending tool.

Returns: JSON: Structured lead + sequence data. CSV: Raw CSV content (same format as MachFive UI download).

Submit multiple leads for batch email sequence generation (ASYNC).

Returns IMMEDIATELY with a list_id. Processing runs in the background.

IMPORTANT — after calling this, you MUST:

1. Call get_list_status with the returned list_id

2. Poll every 15-30 seconds until processing_status is 'completed' or 'failed'

3. When completed, call export_list to get the results

You must have a campaign_id first. Call list_campaigns if you don't have one.

Args: campaign_id: Campaign UUID (from list_campaigns). leads_json: JSON array of lead objects. Each lead MUST have an 'email' field. Optional fields: name, title, company, company_website, linkedin_url. Example: '[{"email":"jane@acme.com","name":"Jane Doe","company":"Acme"}]' email_count: Number of emails per lead, 1-5 (default 3). list_name: Display name for this batch in MachFive UI. email_signature: Signature appended to each email. campaign_angle: Additional context/angle for personalization. approved_ctas: Comma-separated CTAs. Omit to use campaign defaults.

Returns: list_id and status. Use list_id to poll with get_list_status, then export with export_list when completed.

Generate a personalized cold email sequence for ONE lead.

This is SYNCHRONOUS — the request takes 3-10 minutes because MachFive researches the prospect and crafts unique emails. Do NOT retry if it seems slow; wait for the response.

You must have a campaign_id first. Call list_campaigns if you don't have one.

Args: campaign_id: Campaign UUID (from list_campaigns). email: Lead's email address (REQUIRED). name: Lead's full name (improves personalization). title: Lead's job title (improves personalization). company: Lead's company name (improves personalization). company_website: Company URL for AI research. linkedin_url: LinkedIn profile URL for deeper personalization. email_count: Number of emails in sequence, 1-5 (default 3). list_name: Display name for this list in MachFive UI. email_signature: Signature appended to each email. campaign_angle: Additional context/angle for personalization. approved_ctas: Comma-separated CTAs (e.g. "Direct Meeting CTA, Lead Magnet CTA"). Omit to use campaign defaults.

Returns: The generated email sequence (step, subject, body per email) plus credits remaining. If the request times out, use the returned list_id with get_list_status and export_list to recover results.

Check the processing status of a lead list.

Use this to POLL after calling generate_batch. Call every 15-30 seconds until processing_status is 'completed' or 'failed'.

When completed: call export_list to download results. When failed: the batch cannot be exported; submit a new batch.

Args: list_id: The list UUID (from generate_batch or generate_sequence response).

Returns: Status details including processing_status, leads_count, and emails_created (when completed).

List campaigns in the user's MachFive workspace.

CALL THIS FIRST before generate_sequence or generate_batch — you need a campaign ID to generate emails. If the user hasn't specified a campaign, call this and ask them to pick one.

Args: query: Optional search string to filter campaigns by name (case-insensitive substring match). Leave empty to list all.

Returns: JSON array of campaigns with id, name, and created_at. Use the 'id' field as campaign_id in generate calls.

List lead lists (batch jobs) in the user's MachFive workspace.

Useful for browsing past batches, checking what's in progress, or finding a list_id to export. Results are ordered newest first.

Args: campaign_id: Filter by campaign UUID (optional). status: Filter by processing status: 'pending', 'processing', 'completed', or 'failed' (optional). limit: Max results to return, 1-100 (default 20). offset: Pagination offset (default 0).

Returns: List of lead lists with id, name, status, and timestamps.