kudosity-contacts-lists

Files (1)

• SKILL.md

SKILL.md (first lines)

# Contact Lists & Contacts

Lists are how you send to many recipients at once. All list and contact operations are on the **V1 API**.

## Authentication

V1 uses **HTTP Basic**, not the `x-api-key` header the V2 endpoints use:

- Header: `Authorization: Basic {base64(KUDOSITY_API_KEY:KUDOSITY_API_SECRET)}` — `curl -u` does this for you
- **Both** `KUDOSITY_API_KEY` and `KUDOSITY_API_SECRET` are required. V1 will not accept the key alone.
- Credentials come from the Kudosity dashboard under **Developers → API Settings**

- **Base URL**: `https://api.transmitsms.com`
- **Content-Type**: `application/x-www-form-urlencoded` — form fields, not JSON

## Create a list

**Endpoint:** `POST /add-list.json`

- `name` (string, required) — a unique name for the list
- `field_1` … `field_10` (optional) — custom field names. `firstname` and `lastname` exist by default.

```bash
curl -s -X POST "https://api.transmitsms.com/add-list.json" \
  -u "${KUDOSITY_API_KEY}:${KUDOSITY_API_SECRET}" \
  -H "User-Agent: kudosity-skills/0.2.1" \
  -d "name=My Campaign List&field_1=email&field_2=postcode"
```

The response returns the list `id`. Keep it — everything below needs it.

## Add one contact

**Endpoint:** `POST /add-to-list.json`

- `list_id` (integer, required)
- `msisdn` (string, required) — E.164 international format
- `countrycode` (optional) — 2-letter ISO code; auto-formats local numbers
- `first_name`, `last_name`, `field_1` … `field_10` (optional)

```bash
curl -s -X POST "https://api.transmitsms.com/add-to-list.json" \
  -u "${KUDOSITY_API_KEY}:${KUDOSITY_API_SECRET}" \
  -H "User-Agent: kudosity-skills/0.2.1" \
  -d "list_id=4213644&msisdn=0491570156&countrycode=AU&first_name=John&last_name=Doe&field_1=john@example.com"
```

**An existing contact is ignored, not updated.** Use `POST /edit-list-member.json` to change one.

## Bulk import from a CSV

**Endpoint:** `POST /add-contacts-bulk.json`

Either `list_id` (add to an existing list) **or** `name` (create a new list and return its ID) is required.

- `file_url` — a **direct** URL to the CSV. Not a redirect, not a local path. The file must have a column headed `mobile`. Basic auth in the URL is supported: `https://user:pass@host/file.csv`
- `countrycode` (optional) — formats numbers on import
- `field_n` (optional) — create or map a custom field. CSV headers matching a custom field name map automatically: a column headed `email` maps to `field_1=email`.

Expected CSV shape — **the column order matters**:

```csv
Firstname,Lastname,Mobile,"Custom Field 1"
Jane,Doe,61412345678,10.44
```

Only `Mobile` is strictly required.

```bash
curl -s -X POST "https://api.transmitsms.com/add-contacts-bulk.json" \
  -u "${KUDOSITY_API_KEY}:${KUDOSITY_API_SECRET}" \
  -H "User-Agent: kudosity-skills/0.2.1" \
  -d "list_id=4213644&file_url=https://example.com/contacts.csv&countrycode=AU&field_1=email"
```

> ⚠️ **`200` does not mean the contacts were imported.** It means the request reached the server, nothing more. There is no error returned if the import itself fails — a bad `file_url` yields a list ID that is then silently deleted.
>
> **You must poll `add-contacts-bulk-progress.json` to find out what happened.**

Unlike single-contact adds, **bulk import updates existing contacts** rather than ignoring them.

## Check import progress

**Endpoint:** `POST /add-contacts-bulk-progress.json` — `list_id` required.

Lists over 50,000 contacts take a while. This is also the only way to see import errors.

```bash
curl -s -X POST "https://api.transmitsms.com/add-contacts-bulk-progress.json" \
  -u "${KUDOSITY_API_KEY}:${KUDOSITY_API_SECRET}" \
  -d "list_id=4213644"
```

```json
{ "list_id": 4214121, "status": "completed", "importlength": 2, "completed": 2,
  "duplicates": 0, "skipped": 0, "optout": 0, "imported": 2 }
```

| Field | Meaning |
|---|---|
| `status` | `completed`, `in progress` or `failed` |
| `importlength` | Total rows in the file, **including invalid numbers** |
| `completed` | Rows processed — equals `importlength` when done |
| `imported` | Rows actually added |
| `duplicates` | Matched an existing contact; only the first is kept |
| `skipped` | Blank rows, invalid numbers, or a blank `mobile` cell |
| `optout` | Already opted out — **not imported** |

`imported` is usually lower than `importlength`. Report `imported` to the user, not the file's row count, and surface `skipped` — that's where a malformed export shows up.

## Opt a contact out

**Endpoint:** `POST /optout-list-member.json`

- `msisdn` (required) — E.164
- `list_id` — the list to opt out of. **`0` opts out of every list.**

```bash
curl -s -X POST "https://api.transmitsms.com/optout-list-member.json" \

From kudosity/skills, MIT.

More from kudosity/skills