API Documentation

How it works

Text Your List's API is cloud-hosted. You send a request to https://textyourlist.com/api/make/send from anywhere, Make, Zapier, a Python script, an AI agent, and the message is delivered through your desktop app to your phone.

The flow is:

1. Your automation or code calls POST /api/make/send with your API key.
2. The server creates a queued job and assigns it to your desktop app.
3. Your open desktop app picks up the message within seconds and sends it via Messages (Mac) or Phone Link (Windows).
4. Send history and counters update in real time.

Authentication

All API endpoints require a Bearer token in the Authorization header.

Get your API key

1. Open the Text Your List desktop app.
2. Go to Developer in the left sidebar.
3. Under API Keys, enter a name (e.g. "Make integration") and click Create.
4. Copy the key immediately. It is shown only once. It is stored on our server and works even when your app is closed.

To revoke a key, return to Developer → API Keys → Revoke. Any Make/Zapier scenario using the revoked key will stop working immediately.

Pass the key in every request

Authorization: Bearer tbk_your_api_key_here
Content-Type: application/json

Send one message to one person Pro

curl -X POST https://textyourlist.com/api/make/send \
  -H "Authorization: Bearer tbk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12125550100",
    "message": "Hey! Just wanted to follow up on your quote."
  }'

curl -X POST https://textyourlist.com/api/make/send \
  -H "Authorization: Bearer tbk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+12125550100",
    "message": "Here is your custom proposal.",
    "image_url": "https://s3.amazonaws.com/your-bucket/proposal.jpg"
  }'

{
  "job_id": "3f2d...",
  "message_id": "9a1c...",
  "status": "queued",
  "preview": "Here is your custom proposal."
}

Send to a whole contact list Pro

Use this when you want to kick off a full campaign and send a message to everyone on one of your saved contact lists, personalized for each person.

curl -X POST https://textyourlist.com/api/make/send-to-list \
  -H "Authorization: Bearer tbk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "list_name": "April Leads",
    "template_name": "Follow Up",
    "pace_seconds": 7
  }'

curl -X POST https://textyourlist.com/api/make/send-to-list \
  -H "Authorization: Bearer tbk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "list_name": "April Leads",
    "template": "Hey {first_name}, just following up, let me know if you have questions!",
    "campaign_name": "April Follow-Up",
    "pace_seconds": 7
  }'

{
  "job_id": "abc123-...",
  "campaign_name": "April Follow-Up",
  "list": "April Leads",
  "status": "queued",
  "queued": 147,
  "skipped_suppressed": 3,
  "skipped_invalid": 1,
  "skipped_duplicate": 0,
  "note": "Job is queued and will send when the desktop app is open."
}

Look up your lists and templates

Not sure of the exact name of a list or template? These endpoints let any tool (including an AI agent) look them up before sending.

curl https://textyourlist.com/api/make/lists \
  -H "Authorization: Bearer tbk_your_api_key"

[
  { "id": 12, "name": "April Leads", "row_count": 150, "created_at": "2026-04-01T..." },
  { "id": 11, "name": "VIP Clients", "row_count": 42, "created_at": "2026-03-15T..." }
]

curl https://textyourlist.com/api/make/templates \
  -H "Authorization: Bearer tbk_your_api_key"

[
  { "id": 5, "name": "Follow Up", "preview": "Hey {first_name}, just following up..." },
  { "id": 4, "name": "Event Reminder", "preview": "Don't forget, the event is tomorrow..." }
]

Desktop behavior & send speed

How fast messages go out, and whether they need your approval first, is controlled by the API send behavior setting in your Account settings. You can also override this per-request using the pace_seconds field.

You can configure this setting in the desktop app: Account → Api send behavior.

Mac vs Windows preference

If you have both Mac and Windows desktops with Text Your List installed, you can control which one handles API sends.

Set your preference in Account → Api send behavior → Send platform.

Suppression list

Numbers on the suppression list are automatically skipped in all bulk and API sends.

[
  { "phone": "+12125550100", "reason": "Opted out", "created_at": "2026-04-01T12:00:00Z" }
]

curl -X POST https://textyourlist.com/api/suppression \
  -H "Authorization: Bearer tbk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+12125550100", "reason": "Opted out"}'

curl -X DELETE "https://textyourlist.com/api/suppression/%2B12125550100" \
  -H "Authorization: Bearer tbk_your_key"

Errors & limits

All error responses return JSON with an error field: {"error": "description"}

Make setup (step by step)

Connect Make to Text Your List using the HTTP module.

1. In your Make scenario, add an HTTP → Make a request module.
2. Set the URL to: https://textyourlist.com/api/make/send
3. Set the Method to POST.
4. Under Headers, add:
   • Authorization → Bearer tbk_your_api_key
   • Content-Type → application/json
5. Set Body type to Raw and Content type to JSON (application/json).
6. In the Request content body, enter:
   Copy

   {"phone": "{{phone_variable}}", "message": "{{message_variable}}"}

   Replace {{phone_variable}} and {{message_variable}} with your scenario data mappings. To attach an image, add "image_url": "{{image_url_variable}}" (omit the field entirely if you're not sending an image).
7. Enable Follow all redirects (required for this endpoint).
8. Save and run your scenario.

Zapier setup (step by step)

1. In your Zap, add a Webhooks by Zapier action.
2. Choose POST as the event type.
3. Set the URL to: https://textyourlist.com/api/make/send
4. Set Payload type to JSON.
5. Under Data, add two fields:
   • phone → map from your trigger data (e.g. a form field)
   • message → your message text or a mapped variable
6. Under Headers, add: Authorization: Bearer tbk_your_api_key
7. Test the step to confirm a 201 response.

AI agent / Claude setup

If you use an AI assistant like Claude, you can give it your API key and tell it to send texts in plain English. No coding or automation setup needed.

How to set it up

1. Generate an API key in the Developer tab of the desktop app (see Authentication above).
2. Give the key to your AI assistant and ask it to save it as a secret or environment variable called TYL_API_KEY.
3. That's it. Now you can say things like:
   • "Send 'I hope you're having a good day' to 9085550142"
   • "Text John at 9085550142 that dinner is at 7"
   • "Send my Follow Up template to my April Leads list"
   • "Text everyone on my VIP list that the sale starts tomorrow"

The agent handles everything. It knows to call the API, pass your key, and format the request correctly. You just tell it what to say and who to send it to.

For developers: quick integration reference

If you're building something yourself or wiring up an agent framework, here's the minimum you need:

# Single send, works from any machine, no app required at call time
curl -X POST https://textyourlist.com/api/make/send \
  -H "Authorization: Bearer $TYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "9085550142", "message": "Hey, just checking in!"}'

# List send, agent checks available lists first, then sends
curl https://textyourlist.com/api/make/lists \
  -H "Authorization: Bearer $TYL_API_KEY"

curl -X POST https://textyourlist.com/api/make/send-to-list \
  -H "Authorization: Bearer $TYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_name": "April Leads", "template_name": "Follow Up", "pace_seconds": 7}'

Tool definition (for agent frameworks)

If you're integrating with an agent framework that uses tool/function calling (Claude API, OpenAI, etc.):

{
  "name": "send_text",
  "description": "Send a text message from the user's own phone number via Text Your List.",
  "parameters": {
    "type": "object",
    "properties": {
      "phone":     { "type": "string", "description": "Recipient phone number (US format, e.g. +12125550100 or 9085550142)" },
      "message":   { "type": "string", "description": "Message body. Max 1600 characters." },
      "image_url": { "type": "string", "description": "Optional. Public URL of an image to send as MMS (JPEG, PNG, GIF)." }
    },
    "required": ["phone", "message"]
  }
}