Metadata-Version: 2.4
Name: heyleads
Version: 1.0.0
Summary: Official Python client for the HeyLeads API (LinkedIn outreach): campaigns, leads, lists, inbox, webhooks. Standard library only.
License-Expression: MIT
Project-URL: Homepage, https://app.heyleads.so/developers
Project-URL: Documentation, https://app.heyleads.so/developers
Keywords: heyleads,linkedin,outreach,api,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# heyleads (Python)

Python client for the [HeyLeads API](https://app.heyleads.so/developers). **Standard library only** (no `requests`, no dependencies); Python 3.9+.

## Install

```bash
pip install heyleads
```

Create an API key in HeyLeads under **Settings → Integrations → API keys** (it starts with `hl_live_`) and keep it in an environment variable.

```python
import os
from heyleads import HeyLeads, HeyLeadsError

hl = HeyLeads(api_key=os.environ["HEYLEAD_API_KEY"])  # talks to https://app.heyleads.so unless you pass base_url

campaign = hl.campaigns.create({"name": "Founders, Q4"})  # a draft: nothing is sent yet
hl.campaigns.add_leads(campaign["id"], rows=[{"fullName": "Ada Lovelace", "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace"}])  # queued
hl.campaigns.launch(campaign["id"])  # running, not "sent": the engine paces every action within each account's limits

for lead in hl.leads.iterate(status="active"):  # follows the cursor for you
    print(lead["fullName"])

try:
    hl.lists.create("")
except HeyLeadsError as e:
    print(e.status, e.code, e.message, e.field_errors, e.request_id)
```

## Good to know

- **Dicts in, dicts out**, with the API's own camelCase keys (`fullName`, `linkedinUrl`, `nextCursor`), so nothing is lost in translation and the [API reference](https://app.heyleads.so/developers/reference) is the documentation for every field. Options that are Python keyword arguments are snake_case and sent as camelCase (`campaign_id` → `campaignId`; `from_` → `from`).
- **Queued, not sent.** There is no "send now": adding leads to a campaign is how HeyLeads contacts anyone, and a return means queued / running. People on the blacklist or marked do-not-contact are skipped and counted in the answer.
- **Errors** are `HeyLeadsError` with `status`, `code`, `message`, `request_id`, and, for a 422, `field_errors` / `issues`. A network failure or timeout has `status == 0`.
- **Retries.** A `429` is waited out using `Retry-After` (for any method: it was refused before it ran). Repeatable requests (`GET`, `PUT`, `DELETE`, and queued LinkedIn actions, which carry an `Idempotency-Key`) are also retried after a `502`/`503`/`504` or a network error; a `POST`/`PATCH` that may have run is **never** repeated. Tune with `max_retries` (default 2), `timeout` (30 s) and `max_retry_wait_seconds` (30: a longer `Retry-After` raises so you can decide).
- **Paging.** `leads.list` / `inbox.threads` return `{items, nextCursor, total}`; `leads.iterate`, `lists.iterate_leads` and `inbox.iterate_threads` walk every page.
- **Waiting for an action.** `hl.actions.wait(action["id"])` polls until it finishes (default up to 5 minutes); prefer webhooks in production.
- **Webhooks.** Verify a delivery against the **raw** body:

```python
from heyleads import construct_webhook_event

@app.post("/heylead")
def hook():
    try:
        event = construct_webhook_event(os.environ["HEYLEAD_WEBHOOK_SECRET"], request.headers.get("x-heylead-signature"), request.get_data())  # raises ValueError if invalid or older than 5 minutes
    except ValueError:
        return "", 400
    if event["event"] == "lead.positive_reply":
        handle(event["data"])
    return "", 200
```

The method list mirrors `GET /api/v1/openapi.json` one to one (`heyleads.SDK_OPERATIONS` maps each operation id to its method, and a test fails if they drift). The tests run the client against the real API handlers over HTTP.
