Yirlo SDK for JavaScript and Python

Get your API key

Generate a key from the API Keys page in the Yirlo app. Each one carries the prefix yk_live_, and a single key authenticates REST calls, the MCP server and every SDK.

Keep it in an environment variable called YIRLO_API_KEY rather than in source code. Both examples on this page read it from there. If a key leaks, delete it on the same page and create a new one.

Install from npm or PyPI

For JavaScript, run npm install yirlo. The package has no dependencies and works on Node 18+ and in browsers. For Python, run pip install yirlo, which needs Python 3.8+ and pulls in nothing beyond the standard library.

To upgrade later, run npm update yirlo or pip install -U yirlo. If you would rather keep one file in your repo, the same code is served at https://yirlo.com/sdk/yirlo.js and https://yirlo.com/sdk/yirlo.py, and you can import either straight from a lib folder.

Both SDKs were tested against the live API, 20 of 20 checks passing for each. In a browser, remember that a page shipping your key to visitors exposes it, so call the SDK from a server or a private script when the key is yours alone.

Your first calls

In JavaScript:

import { Yirlo } from "yirlo";
const y = new Yirlo(process.env.YIRLO_API_KEY);
const account = await y.getAccount();
const { campaigns } = await y.listCampaigns({ project_id: 123 });

In Python:

import os
from yirlo import Yirlo
y = Yirlo(os.environ["YIRLO_API_KEY"])
account = y.get_account()
campaigns = y.list_campaigns(project_id=123)["campaigns"]

Replace 123 with your own project id. The method names match the 33 MCP tools, written in camelCase in JavaScript and snake_case in Python. If you already know a tool from the MCP server, you already know the SDK method.

Required arguments are checked before the call is sent. Leave out project_id on a call that needs it and the SDK stops on your machine with a clear message, so a typo never costs a round trip.

Every method, grouped by job

The SDK's 33 methods fall into a few task groups. A customer's very first project gets created on yirlo.com from their website address, since the first payment is made there. Later projects can be started on the site or in code: call createProject (create_project in Python) with your domain and you get back a project id with the status "creating". Poll the project until it shows "ready", which takes roughly a minute. Campaigns inside a project made through the API sit paused, waiting for you to start them. Four methods handle leads you bring yourself. importLeads and getImport (import_leads and get_import in Python) deal with a CSV upload, while leadsFromPost and listPosts (leads_from_post and list_posts) collect the people who commented or replied on a LinkedIn or X post you wrote, then create a campaign for them. To list the exact method names in your installed copy, run Object.getOwnPropertyNames(Yirlo.prototype) in Node, or [m for m in dir(Yirlo) if m[0] != "_"] in Python. Documentation for the API underneath lives at yirlo.com/api-docs.

• Account and billing: read the account, check the credit balance, buy credit and set auto top-up from the card on file.
• Projects: list them, open one, and create another with createProject once your first project exists, then watch its status move from creating to ready.
• Campaigns: list, create, edit, start, stop and archive campaigns, set daily budgets, change the email instructions and preview the emails a campaign would write.
• Inbox: open any conversation, post a reply, attach a note, change a lead's status, or flag a thread as answered.
• Hot leads: fetch the people who answered with interest, the same ones Yirlo emails to you.
• Analytics: pull results for a project or a campaign.
• Suppression lists: add addresses or domains that must never be emailed.
• Webhooks: set up and maintain signed endpoints that fire on incoming replies and fresh hot leads. You can also trigger a test event, which gives your Zapier, n8n or Make scenario sample data to map fields against.

Errors

When the API answers with an error, the JavaScript SDK throws YirloError with two properties: .status, the HTTP status code, and .body, the response the API sent. The Python SDK raises YirloError with the same information.

Wrap calls that matter in try and catch in JavaScript, or try and except YirloError in Python. A 401 means the key is wrong or deleted. Use the status for the branch you take and log the body, which usually says what to fix.

Script: print hot leads every morning

This Node script prints the hot leads for one project. Save it as hot.mjs next to yirlo.js and run node hot.mjs:

import { Yirlo } from "yirlo";
const y = new Yirlo(process.env.YIRLO_API_KEY);
const { leads } = await y.listHotLeads({ project_id: 123 });
for (const l of leads) console.log(l.name, l.company_name, l.email, l.why_hot);

The Python version, saved as hot.py next to yirlo.py:

import os
from yirlo import Yirlo
y = Yirlo(os.environ["YIRLO_API_KEY"])
for l in y.list_hot_leads(project_id=123)["leads"]:
    print(l["name"], l["company_name"], l["email"])

To get it every morning, schedule it. A cron line such as 0 8 * * 1-5 node /path/to/hot.mjs runs it at 8:00 on weekdays, and you can pipe the output to mail or to a chat webhook. Hot leads also arrive by email as they happen, so this script suits a team that wants one digest in a place of its own choosing.

Script: pause a campaign when bounces climb

Campaign analytics count the people contacted and the bounces, so a script can stop a campaign whose list has gone stale before it hurts your sending. In Node:

const { campaigns } = await y.listCampaigns({ project_id: 123 });
for (const c of campaigns.filter((x) => x.status === "running")) {
  const a = await y.campaignAnalytics({ campaign_id: c.id });
  if (a.contacted >= 50 && a.bounced / a.contacted > 0.05) {
    await y.stopCampaign({ campaign_id: c.id });
    console.log("Stopped", c.name);
  }
}

In Python:

for c in y.list_campaigns(project_id=123)["campaigns"]:
    if c["status"] != "running":
        continue
    a = y.campaign_analytics(campaign_id=c["id"])
    if a["contacted"] >= 50 and a["bounced"] / a["contacted"] > 0.05:
        y.stop_campaign(campaign_id=c["id"])
        print("Stopped", c["name"])

Stopping is reversible: once the list is cleaned up, start the campaign again with startCampaign (start_campaign in Python). A daily cron line is enough for this check.

Questions

Related