Skip to content

Docs / All tools / Loop II: Acquisition

acquisition.campaign.create

Start a campaign from a pain point or company list. Find decision-makers and draft up to five emails for approval.

Charged by the tools it calls. demand.radar 90 (when it starts from a pain), contact.resolve 25 per person found.

Example prompt

Send this to your AI app when Heelo is connected:

Start a campaign to the CTOs of the companies from my last ICP search, with three short e-mails for days 0, 3 and 7. Show me the people and the e-mails before anything is sent.

Input fields

FieldTypeDescription
nameRequiredstringA name for the campaign. It also names the mail sequence.
painstringSource 1: the problem the customers have, in plain words (the ICP's pain). Heelo searches public posts for people who say they have it, and looks up contacts at their companies. Give pain or companies, not both.
companiesarray of objectSource 2: the companies to reach (1 to 200), for example from icp.search. Give pain or companies, not both.
radar_platformsarray of stringWith pain only: the platforms to search, from reddit, bluesky, twitter, web, github and hackernews (default reddit, bluesky, web, github, hackernews).
radar_window_daysintegerWith pain only: how many days back to search.
target_rolesarray of stringThe roles to reach at each company, best first, for example ['head of finance', 'CFO'].
from_domainRequiredstringThe domain the mail is sent from. It must be a sender that can send: acquisition.campaign.create says which one when it is not.
from_namestringThe display name in the From header.
reply_tostringThe mailbox where replies are read, so that a reply stops the sequence for that person. Leave it out to use the deployment's reply address.
stepsRequiredarray of objectThe messages, 1 to 5, for example days 0, 3 and 7. Templates may use {{full_name}}, {{company_domain}} and {{tracking_url}} (a tracked link: put it in at least one step so that a click is attributed to the person). The footer (Advertisement, the postal address and an unsubscribe link) is added to every message.
daily_capintegerThe most messages a day from this domain.
target_contactsintegerStop looking up contacts when this many are found (1 to 200).
contacts_per_companyintegerThe most contacts at one company (1 to 3).
jurisdictionstringThe country of the people to reach, as a two-letter code: US or CA. Other countries are refused (policy, jurisdiction_blocked) before any lookup.
physical_addressstringRequired by law (CAN-SPAM): the sender's postal address, added to every message. Ask the user for it and never make one up. A call without it is refused (policy, missing_statutory_element).
ad_disclosurebooleanRequired by law (CAN-SPAM): must be true. It confirms that each message is an advertisement; the footer says so. Ask the user and never set it on your own. A call without it, or with false, is refused (policy, missing_statutory_element).

Code

The call with the input fields that the tool needs. Replace each word in capitals, such as NAME. Set HEELO_API_KEY to your API key.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/acquisition.campaign.create/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {
        "name": "NAME",
        "from_domain": "example.com",
        "steps": [{"day": 0, "subject_tpl": "SUBJECT_TPL", "body_tpl": "BODY_TPL"}],
        "companies": [{"domain": "example.com"}],
        "physical_address": "PHYSICAL_ADDRESS",
        "ad_disclosure": True,
    }},
    timeout=120,
)
response.raise_for_status()
print(response.json())