Foxreach Cold Outrach

Manage FoxReach cold email outreach — leads, campaigns, sequences, templates, email accounts, inbox, and analytics. Use when the user asks to create leads, m...

Security Scan

The skill's docs and runtime instructions largely match its described purpose (FoxReach API management) but contain inconsistencies — notably references to local SDK/CLI directories that are not included and an expected API key that isn't declared — which warrant caution before installing or running.

Purpose & Capability

Name/description match the instructions (managing FoxReach leads, campaigns, inbox, analytics). However the SKILL.md instructs use of a local Python SDK and CLI located at integrations/sdk-python/ and integrations/cli/ which are not present in the package; it also expects an API key (FOXREACH_API_KEY) but the skill metadata did not declare any required env or primary credential. These are likely packaging/metadata omissions but reduce coherence.

Instruction Scope

Runtime instructions tell the agent to run python -c commands, pip install -e . from integrations paths, and to inject FOXREACH_API_KEY into the environment for invocations. That scope is consistent with an API client skill, but the instructions reference local directories that aren't shipped (no integrations/ folder), which means following them could either fail or, if the author intended external downloads, lead to unexpected installs. The allowed-tools patterns explicitly permit env-var injection and arbitrary python execution (Bash(FOXREACH_API_KEY=* python *)), so if the missing files were later provided or fetched, the skill could execute arbitrary Python with an injected API key.

Install Mechanism

There is no formal install spec (instruction-only), which is low-risk in itself. But SKILL.md advises 'cd integrations/sdk-python && pip install -e .' which attempts an editable install from a local path. Since the referenced directories are not included, this is inconsistent. If an install path were present or fetched later, pip installing arbitrary/unreviewed code from a local or remote path is higher risk. The package should either include the SDK/CLI or provide an auditable external release URL (PyPI/GitHub) rather than relying on undocumented local installs.

Credentials

The skill's operations legitimately require a FoxReach API key (FOXREACH_API_KEY). The metadata, however, lists no required env vars or primary credential, so the true expectation is only visible in SKILL.md. There are no requests for unrelated credentials or broad environment paths. The omission of FOXREACH_API_KEY from the declared requirements is a metadata mismatch that should be corrected so users know what secret will be used.

Persistence & Privilege

The skill does not request 'always: true' and has no install spec that would persist beyond normal agent activity. It does instruct how to configure the CLI with a key, but that is standard for API clients and does not imply elevated system privilege.

What to consider before installing

This skill appears to be a FoxReach API client, but there are some red flags to check before installing or running it: - Do not run the pip install or python commands until you verify what will be installed. SKILL.md instructs 'pip install -e .` from integrations/sdk-python/ and an integrations/cli/ config, but those folders are not included in the package — ask the author where the SDK/CLI come from. - Ask the publisher to update metadata: FOXREACH_API_KEY should be declared as the primary credential so you know a key is required. - If you must test it, use a limited-scope or throwaway API key and run in an isolated environment (container or VM) to limit blast radius. - Prefer a skill that points to an auditable release (PyPI or GitHub release) rather than relying on local editable installs; if the SDK is external, request the exact URL and review its contents before pip installing. - Inspect any integrations/ code before executing; the current package contains only docs (SKILL.md, examples.md, api-reference.md). If the SDK/CLI are later added or fetched automatically, re-evaluate before granting secrets. If the author can provide the missing SDK/CLI files (or point to an official release) and update the manifest to declare FOXREACH_API_KEY, the incoherence would be resolved and the skill would be more straightforward to trust.

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": "[e-mail]", "first_name": "Alice", "company": "Acme"},
    {"email": "[e-mail]", "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.