Campaigns and contact lists

Contact lists

A list holds a phone number and up to six dynamic fields df1–df6 (first name, city, appointment date…).

bash

curl -X POST https://smsprovider-web.vercel.app/api/v1/lists \
  -H "Authorization: Bearer $BATLER_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "VIP customers", "contacts": [{"phone": "0501234567", "df1": "Dana"}, {"phone": "0527654321", "df1": "Yossi"}]}'

Invalid numbers are returned in rejected with a reason; duplicates are merged.
Add/remove: POST / DELETE https://smsprovider-web.vercel.app/api/v1/lists/{id}/contacts (up to 10,000 per call).
In the portal you can import CSV or Excel with column mapping.

Sending a campaign

json

POST https://smsprovider-web.vercel.app/api/v1/campaigns
{
  "list_id": "5b0d2a8e-1d7c-4a35-9a7e-3c1a3b5e9f00",
  "from": "MyBrand",
  "body": "Hi {{df1}}, end of season sale: 20% off! [shop]",
  "links": { "shop": "https://example.com/sale" },
  "unsubscribe": "link",
  "schedule_at": "2026-11-05T09:00:00+02:00"
}

{{df1}}…{{df6}} are replaced with each contact's value.
Unsubscribed contacts and blacklisted numbers are filtered automatically; skip_recent_days (1–14) skips people messaged recently.
The cost is reserved upfront (segments × recipients) and returned as credits_reserved.
Cancel before the scheduled time: POST https://smsprovider-web.vercel.app/api/v1/campaigns/{id}/cancel — credits are released.

Links and click tracking

Every link in a message goes through our shortener: write [link-id] in the text and pass links: { "link-id": "https://…" }. Each recipient gets a unique short link, so you can see who clicked and when (GET https://smsprovider-web.vercel.app/api/v1/campaigns/{id}/clicks, webhook link.clicked). WhatsApp/iMessage previews and bots are not counted as clicks. The short link (~30 chars) counts toward message length.

Unsubscribe (required for marketing messages)

`unsubscribe`	What is added
`link`	Our short unsubscribe link at the end. Click → one-tap confirmation → the number joins your blacklist
`reply`	A "reply to unsubscribe" text — a reply removes the recipient automatically
`none`	Nothing (transactional messages only)

Place the unsubscribe link inside the text with [unsubscribe]. A blacklist.added event is sent for every opt-out.