Yirlo API: run your outbound from code or an AI agent
By the Yirlo team · Product details checked against the app
The Yirlo API gives a script or an AI agent the same controls you have in the app for projects, campaigns, the inbox, budgets and billing. Every request uses an API key you create yourself, and every error comes back as readable JSON. This page covers what you can read and change, how to authenticate, and what a request looks like.
What the Yirlo API lets you do
Send every call to https://yirlo.com/public/api/v1. It suits anyone who wants to watch or steer outbound without opening the dashboard: a developer pushing spend numbers into an internal report, an agency operator running several projects at once, or an AI agent that goes through replies every morning.
Here is what the API covers today:
- Account: who a key belongs to, plus the credit balance, spend by day and a billing activity feed.
- Projects can be listed and fetched, and their daily budget, monthly cap, sender name, My copy and autopilot options can be changed. Analytics and the inbox for a project can be fetched as well.
- For campaigns you can list, create, fetch and edit them, view a preview of the opening email, approve the lead list, start, stop, archive and restore them, and change the daily budget. Reporting covers analytics, delivery status and the people who were contacted.
- The inbox endpoints return conversations and their changes. They let you open a thread and respond within it, flag a thread as handled, and view or edit the note and the status on a lead.
- Hot leads: the people who replied with interest.
- Suppression lists: people and companies you never want emailed, applied across every project.
- Webhooks: list, add, read and delete.
- Tasks and feedback: read your tasks and send feedback to the Yirlo team.
Authentication and your first request
Create your key in the dashboard under API keys (yirlo.com/app/api-keys). To authenticate, send it as the X-API-Key header or as a bearer token in the Authorization header. All endpoints take both.
The quickest check is asking who the key belongs to: curl https://yirlo.com/public/api/v1/me -H "X-API-Key: YOUR_KEY". If the response names your account, the key is good.
The bearer form looks like this: curl https://yirlo.com/public/api/v1/agentapp/projects -H "Authorization: Bearer YOUR_KEY". That returns your projects, and each one carries the id you use in the project routes.
Keep keys out of source control and out of client-side code. A key acts for your account, so store it in an environment variable or a secrets manager and give each script or agent its own key where you can.
Reading and setting project controls
A project stands for one product or company you are promoting. Your first one starts on yirlo.com from the website, which Yirlo then studies; later ones can also be opened with POST /agentapp/projects. From there, GET /agentapp/projects/{id} returns the project, and the API can also update its settings.
Writable settings control the volume and the voice of your outbound: the daily budget, the monthly cap, the sender name, My copy (your own email copy) and the autopilot options. One typical setup is a script that gives a project more daily budget while a campaign is drawing replies, then cuts it back near month end when the monthly cap is almost reached.
Project analytics and the project inbox are readable from the same project routes, so one call sequence can give you results and the latest conversations for a single product.
Managing campaigns through the API
Campaigns are the audiences Yirlo proposes and runs. GET /agentapp/campaigns lists them and POST /agentapp/campaigns creates one. From there you can read a single campaign, edit it, and open its My copy and a preview of its first email before anything is sent.
Campaign controls cover create, edit, start, stop and archive. Each campaign also has its own budget, so you can give a promising audience more room without touching the rest of the project.
For reporting, read the campaign analytics, the send status and the list of leads contacted. An agent that reviews a campaign preview, approves the list when it looks right and starts the campaign gives you a review step you can automate or keep manual.
Working the inbox and hot leads
The inbox endpoints cover the whole reply workflow. List conversations, read a thread, send a reply in it, mark it replied if you answered elsewhere, and set the lead status so your records match what happened. You can also read and write the lead note, which suits an agent that logs context after each exchange.
GET /agentapp/hot-leads returns the interested replies. A morning job can pull that list, pass each thread to a person or an agent for a response and write a note when done: curl https://yirlo.com/public/api/v1/agentapp/hot-leads -H "X-API-Key: YOUR_KEY".
The list of inbox changes lets you poll for what is new since your last check instead of reading every conversation again.
Suppression lists, webhooks and billing
Suppression lists hold people and companies that must not be emailed. They apply to every project on the account, so one entry protects a competitor, a current customer or a person who asked you to stop, whichever product is sending.
You can register an endpoint of your own instead of polling. GET and POST on /agentapp/webhooks list and add webhooks, and an individual webhook can be fetched or removed through its own path.
Billing is read-only for now. GET /billing/balance returns the balance, /agentapp/billing gives the billing overview, /agentapp/billing/usage shows spend by day and /agentapp/billing/activity lists account activity. Since pricing is prepaid credit with a daily budget, a nightly check of balance and usage tells you how many days of sending are left.
Errors and the full reference
When a request fails, the response body is JSON in one shape: {"detail": "..."}. The detail string says what went wrong, so your code can log it directly or hand it to an agent to correct the call. Check the HTTP status code first, then read detail for the reason.
The complete reference, including every route and an OpenAPI file you can import into a client generator or an agent toolset, is at https://yirlo.com/api-docs. If something in the API is missing or unclear, POST /feedback sends a note straight to the Yirlo team.
What is coming next for the API
You can already hand Yirlo a list of your own contacts: send a CSV with as many as 30,000 rows to POST /agentapp/campaigns/import, and it builds a campaign around those exact people and starts it right away. Connecting your own domains and mailboxes for sending is coming soon. Until then, every message leaves through ready-to-send mailboxes that Yirlo sets up and looks after for you.
Since Yirlo sources the companies and contacts for every campaign on its own, you steer campaigns through settings, copy, budgets and approvals instead of handing over lists.
Questions
Where do I get an API key?
Open API keys in your dashboard (yirlo.com/app/api-keys) and create a key there. Authenticate by passing it in the X-API-Key header, or by sending it as a bearer token in Authorization.
What is the base URL?
https://yirlo.com/public/api/v1. Every route on this page sits under that address.
Can I create a new project through the API?
A new account's initial project is created on yirlo.com, where you type in your website's domain and pay for the first time. Later projects can be created on that same site or programmatically, by sending the domain through an SDK, the MCP server or a plain API call. Projects created that way start with every campaign paused until you start one. Once setup completes, the API lets you read the project's details and update its settings.
Can I create and start campaigns from code?
Yes. POST /agentapp/campaigns creates one, and you can edit it, preview its first email, approve its lead list, start it, stop it, archive it and set its daily budget.
Can an AI agent reply to leads?
Yes. Your agent can browse conversations, open any thread, post a response, flag it as handled and change the lead's status. Whether a human signs off on replies first is up to you.
How are errors returned?
As JSON in the form {"detail": "..."}, with a failing HTTP status. The detail text describes the problem.
Can I check my balance and spend through the API?
Yes. GET /billing/balance gives the balance, and the /agentapp/billing routes give an overview, spend by day and account activity.
Does the suppression list apply to all my projects?
Yes. Lists of people and companies apply to every project on the account.
Can I search for leads or import my own through the API?
Importing contacts you already have is live. Today the API covers projects and campaigns, lead list imports, imports of the people who commented on your own LinkedIn or X posts, the inbox where you read and answer conversations, hot leads, analytics, billing and credit, suppression lists, and webhooks.
Where is the full reference?
At https://yirlo.com/api-docs, which also links the OpenAPI file for client generators and agent tools.