kudosity-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Get set up with Kudosity

Everything needed before the first message sends. Four things have to be true:

1. A Kudosity account exists
2. API credentials are in the environment
3. The right credential is used for the right API
4. A **sender** is available to send from

Steps 1–3 are the usual focus. **Step 4 is the one that's missed** — credentials can be perfectly valid and a send still fails because there's nothing to send *from*.

## 1. Account

If the person has no account, direct them to **https://kudosity.com/signup**.

Account creation is not available through the API — it happens in a browser. An agent can't complete this step on someone's behalf; hand them the link and wait.

## 2. Find the credentials

Once signed in: **Developers → API Settings**.

| Credential | Environment variable | Needed for |
|---|---|---|
| API Key | `KUDOSITY_API_KEY` | Everything |
| API Secret | `KUDOSITY_API_SECRET` | The V1 API only — contacts, lists, bulk SMS, reporting, balance |

If the API Secret field is blank, it hasn't been generated yet. It has to be created in the dashboard before V1 calls will work — there's no API to mint one.

## 3. Which credential for which API

Kudosity runs two APIs. This is the single biggest source of confusion, and a 401 is almost always this.

| | Base URL | Auth |
|---|---|---|
| **V2** — single-recipient SMS, MMS, WhatsApp, RCS, webhooks | `api.transmitmessage.com` | Header `x-api-key: {KUDOSITY_API_KEY}` |
| **V1** — contact lists, bulk/list sends, scheduling, reporting, balance | `api.transmitsms.com` | HTTP Basic — base64 of `{KUDOSITY_API_KEY}:{KUDOSITY_API_SECRET}` |

The V2 API never uses the secret. The V1 API always needs both.

## 4. Store them

> 🔒 **Credentials stay on the user's machine.** Store them as environment variables. They are not sent to the model, to Kudosity's MCP server, or to any cloud service — they are used only when making direct API requests. On a shared machine, anyone who can read the shell profile can read these values.

Never write credentials into source files, and never echo them back in full.

Shell profile (`~/.zshrc`, or `~/.bashrc` for bash):

```bash
export KUDOSITY_API_KEY="..."
export KUDOSITY_API_SECRET="..."
```

If the variable is already set, replace the existing line rather than appending a second one — a duplicate export silently wins and makes a stale key look like a valid one.

For a project rather than a shell, a `.env` file works equally well. Add it to `.gitignore`.

## 5. Verify before sending

Two read-only calls. Neither sends anything or costs money.

**V2 — key only:**

```bash
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://api.transmitmessage.com/v2/sms?limit=1" \
  -H "x-api-key: ${KUDOSITY_API_KEY}"
```

`200` means the key works. `401` or `403` means it doesn't.

**V1 — key and secret:**

```bash
curl -s "https://api.transmitsms.com/get-balance.json" \
  -u "${KUDOSITY_API_KEY}:${KUDOSITY_API_SECRET}"
```

Returns the account balance and currency. An error here with a working V2 check means the **secret** is wrong or missing — the key is already proven good.

## 6. Get a sender

**A verified sender is required. Without one, sends fail even with perfect credentials.**

What counts as a sender depends on the channel:

| Channel | Sender is |
|---|---|
| SMS / MMS | A number registered to the account, or an approved alphanumeric sender ID (max 11 characters) |
| WhatsApp | A registered WhatsApp Business number, E.164. Omit it and the account's default is used. |
| RCS | **A registered RCS agent ID — not a phone number.** Passing a number fails validation. |

### Check what the account already has

Don't guess — ask:

```bash
curl -s "https://api.transmitmessage.com/v2/senders/registrations" \
  -H "x-api-key: ${KUDOSITY_API_KEY}" \
  -H "User-Agent: kudosity-skills/0.2.1"
```

For virtual numbers on the account, V1 answers the same question:

```bash
curl -s "https://api.transmitsms.com/get-numbers.json?filter=owned" \
  -u "${KUDOSITY_API_KEY}:${KUDOSITY_API_SECRET}"
```

### Getting a new sender

Senders are provisioned through the Kudosity dashboard or by talking to a Kudosity account contact. Alphanumeric sender IDs and RCS agents both need approval and are not instant — factor that into any "we'll be live tomorrow" plan.

### Is my sender ready to send?

A sender that exists is not necessarily a sender you can use. `GET /v2/senders/registrations` returns `details.alphanumeric.status`, which moves through the registry lifecycle:

`NEW` → `SUBMITTED_TO_REGISTRY` → `PENDING_CUSTOMER` → `PENDING_APPROVAL` → `VERIFIED` → `READY_TO_USE`

> **`VERIFIED` does not mean you can send.** It means *Provisioning*. **`READY_TO_USE` is the one that means ready.** Sending on `VERIFIED` fails, and the failure looks like a mystery rather than a sender problem.

From kudosity/skills, MIT.

More from kudosity/skills