AGENT SKILL

foxreach

Manage FoxReach cold email outreach — leads, campaigns, sequences, templates, email accounts, inbox, and analytics. Use when the user asks to create leads, manage campaigns, check analytics, send outreach, manage email sequences, or anything related to the FoxReach API.

License 许可
MIT
最近更新
2026-06-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
foxreach
description
Manage FoxReach cold email outreach — leads, campaigns, sequences, templates, email accounts, inbox, and analytics. Use when the user asks to create leads, manage campaigns, check analytics, send outreach, manage email sequences, or anything related to the FoxReach API.
allowed-tools
Bash(python *), Bash(cd *), Bash(FOXREACH_API_KEY=* python *), Read, Grep, Glob
argument-hint
[resource] [action] [options]

03 SKILL.md 正文

FoxReach API Management Skill

You are managing the FoxReach cold email outreach platform through its Python SDK and CLI. This skill covers all API operations for leads, campaigns, sequences, templates, email accounts, inbox, and analytics.

Setup & Authentication

The Python SDK is at integrations/sdk-python/ and the CLI is at integrations/cli/. Both use API key authentication with keys prefixed otr_.

Check if the SDK is available:

python -c "from foxreach import FoxReach; print('SDK ready')"

If not installed, install it:

cd integrations/sdk-python && pip install -e .

Authentication — Always get the API key from the user or environment before making calls. Never hardcode keys. Use environment variable injection:

FOXREACH_API_KEY=otr_... python script.py

Or use the CLI config:

cd integrations/cli && PYTHONPATH=. python -m foxreach_cli.main config set-key --key otr_...

How to Execute Operations

Write inline Python scripts using the SDK. Always follow this pattern:

import json
from foxreach import FoxReach

client = FoxReach(api_key="otr_USER_KEY_HERE")

# ... perform operation ...

client.close()

For quick operations, use one-liners:

python -c "
from foxreach import FoxReach
client = FoxReach(api_key='otr_...')
result = client.leads.list(page_size=10)
for lead in result:
    print(f'{lead.id}  {lead.email}  {lead.status}')
print(f'Total: {result.meta.total}')
client.close()
"

Resource Reference

For complete API details, see api-reference.md. For usage examples of every operation, see examples.md.


Quick Reference — Available Operations

Leads

Action Method Notes
List client.leads.list(page=1, page_size=50, search=..., status=..., tags=...) Paginated, filterable
Get client.leads.get(lead_id) Returns single Lead
Create client.leads.create(LeadCreate(email=..., first_name=..., ...)) Deduplicates by email
Update client.leads.update(lead_id, LeadUpdate(company=..., ...)) Partial update
Delete client.leads.delete(lead_id) Soft-delete

Campaigns

Action Method Notes
List client.campaigns.list(status=...) Filter by draft/active/paused/completed
Get client.campaigns.get(campaign_id) Includes stats
Create client.campaigns.create(CampaignCreate(name=..., ...)) Creates in draft
Update client.campaigns.update(campaign_id, CampaignUpdate(...)) Can't edit if active
Delete client.campaigns.delete(campaign_id) Must be draft
Start client.campaigns.start(campaign_id) Transitions to active
Pause client.campaigns.pause(campaign_id) Pauses sending
Add Leads client.campaigns.add_leads(campaign_id, [lead_ids]) Bulk add
Add Accounts client.campaigns.add_accounts(campaign_id, [account_ids]) Assign senders

Sequences (nested under campaigns)

Action Method Notes
List client.campaigns.sequences.list(campaign_id) All steps
Create client.campaigns.sequences.create(campaign_id, SequenceCreate(body=..., ...)) Add step
Update client.campaigns.sequences.update(campaign_id, seq_id, SequenceUpdate(...)) Edit step
Delete client.campaigns.sequences.delete(campaign_id, seq_id) Remove step

Templates

Action Method Notes
List client.templates.list() Paginated
Get client.templates.get(template_id) Single template
Create client.templates.create(TemplateCreate(name=..., body=...)) New template
Update client.templates.update(template_id, TemplateUpdate(...)) Partial update
Delete client.templates.delete(template_id) Remove

Email Accounts

Action Method Notes
List client.email_accounts.list() Paginated
Get client.email_accounts.get(account_id) With health metrics
Delete client.email_accounts.delete(account_id) Remove

Inbox

Action Method Notes
List Threads client.inbox.list_threads(category=..., is_read=..., ...) Filterable
Get client.inbox.get(reply_id) Full thread
Update client.inbox.update(reply_id, ThreadUpdate(is_read=..., ...)) Mark read/starred

Analytics

Action Method Notes
Overview client.analytics.overview() Dashboard KPIs
Campaign client.analytics.campaign(campaign_id) Metrics + daily stats

Pagination

List endpoints return PaginatedResponse objects:

result = client.leads.list(page=1, page_size=50, search="acme")

# Access data
for lead in result:
    print(lead.email)

# Check pagination info
print(f"Page {result.meta.page}/{result.meta.total_pages}, {result.meta.total} total")

# Get next page
if result.has_next_page():
    next_result = result.next_page()

# Auto-paginate through ALL results
for lead in client.leads.list().auto_paging_iter():
    print(lead.email)

Error Handling

Always wrap API calls in try/except:

from foxreach import FoxReach, NotFoundError, RateLimitError, AuthenticationError, FoxReachError

try:
    lead = client.leads.get("cld_nonexistent")
except NotFoundError:
    print("Lead not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except FoxReachError as e:
    print(f"API error: {e}")

Template Variables & Personalization

Email bodies support variable substitution using {{variable}} syntax:

  • {{firstName}}, {{lastName}}, {{email}}
  • {{company}}, {{title}}, {{phone}}
  • {{website}}, {{linkedinUrl}}
  • Custom fields: {{customFieldName}}

Spintax is also supported: {Hi|Hey|Hello} {{firstName}}


Common Workflows

1. Full Campaign Setup

When the user wants to set up a complete campaign, follow these steps in order:

  1. Create the campaign with campaigns.create()
  2. Add sequence steps with campaigns.sequences.create() for each email in the chain
  3. Add leads with campaigns.add_leads()
  4. Assign email accounts with campaigns.add_accounts()
  5. Start the campaign with campaigns.start()

2. Check Campaign Performance

  1. Get campaign analytics with analytics.campaign(id)
  2. Show sent, delivered, bounced, replied, opened stats
  3. Show reply rate and bounce rate
  4. If daily_stats are available, summarize trends

3. Manage Inbox

  1. List unread threads with inbox.list_threads(is_read=False)
  2. Categorize replies by updating with inbox.update(id, ThreadUpdate(category="interested"))
  3. Common categories: interested, not_interested, out_of_office, wrong_person, unsubscribe

4. Bulk Lead Import

For adding multiple leads, create them one by one (the API deduplicates by email):

leads_data = [
    {"email": "a@example.com", "first_name": "Alice", "company": "Acme"},
    {"email": "b@example.com", "first_name": "Bob", "company": "Beta"},
]
created = []
for data in leads_data:
    lead = client.leads.create(LeadCreate(**data))
    created.append(lead)
    print(f"Created: {lead.id} - {lead.email}")

Important Notes

  • Base URL: https://api.foxreach.io/api/v1
  • Rate limit: 100 requests per minute. The SDK auto-retries on 429.
  • ID prefixes: Leads cld_, Campaigns cmp_, Replies rpl_, Templates tpl_
  • Timezone: All datetimes in UTC ISO 8601 format.
  • Sending days: Array of integers, 1=Monday through 7=Sunday.
  • Sending hours: 0-23 range, in the campaign's timezone.
  • Campaign status flow: draft → active → paused → active → completed
  • Soft deletes: Leads are soft-deleted and can reappear on re-import.
  • Always confirm with the user before destructive operations (delete, start campaign).
  • When listing data, default to showing a formatted summary, not raw JSON.
  • When creating resources, confirm the details with the user before executing.

04 同仓库更多 Skills

javimosch
javimosch/open-claw-skills

crowd-prompting

A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.

★ 0
javimosch
javimosch/open-claw-skills

ceaser

Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).

★ 0
javimosch
javimosch/open-claw-skills

ceaser-send

Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.

★ 0
javimosch
javimosch/open-claw-skills

dilemm-ai

Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).

★ 0
javimosch
javimosch/open-claw-skills

moldium

Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.

★ 0
javimosch
javimosch/open-claw-skills

arxiv-paper-reviews

Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.

★ 0