---
title: "Get started"
description: "From an API key to your first message, step by step."
url: "https://docs.goomzo.africa/docs/developers/get-started"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Get started"
related:
  - /docs/developers/ts-sdk
  - /docs/developers/python-sdk
  - /docs/developers/php-sdk
  - /docs/developers/go-sdk
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Get started

> From an API key to your first message, step by step.

This guide takes you from nothing to a message on a customer's phone and an event in your own system. It takes
about ten minutes.

## Requirements

- A Goomzo account. Only the organization's owner and admins can create API keys.
- SMS on your account. See [SMS bundles](https://docs.goomzo.africa/docs/help/sms-bundles?utm_source=llms&utm_medium=ai).
- A phone you can receive SMS on, to test with.

## Step 1: Create an API key

1. Open **Settings → API keys** and select **New API key**.
2. Name it after your system, such as **Shop**, and choose the **Messaging** bundle of permissions.
3. Save, and copy the secret. Goomzo shows it only once.

Keep the secret in an environment variable, never in your code:

```bash
export GOOMZO_TOKEN=gzk_...
```

## Step 2: Add a customer

```bash
curl https://api.goomzo.africa/v1/customers \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ifExists": "update", "customers": [{ "name": "Amina Juma", "phone": "+255712345678" }] }'
```

Use your own phone number, so you receive the message in step 4.

## Step 3: Create a template

```bash
curl https://api.goomzo.africa/v1/templates \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "auth_1", "channel": "sms", "category": "authentication",
        "content": { "text": "Hi {{name|there}}, your code is {{secret.code}}." } }'
```

`{{secret.code}}` is a value you pass when you send. Goomzo delivers it, but keeps it masked as `••••••`.

## Step 4: Send your first message

```bash
curl https://api.goomzo.africa/v1/messages \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-message-1" \
  -d '{ "messages": [{ "to": "+255712345678", "template": "auth_1", "variables": { "code": "482913" } }] }'
```

Your phone receives "Hi Amina, your code is 482913." The answer shows the message with `"status": "sending"`.

## Step 5: Set up a webhook

1. Open **Settings → Webhooks** and select **New endpoint**.
2. Enter your HTTPS URL, and choose `message.delivered` and `message.failed`.
3. Select **Send test event** to check your receiver.

Send another message: your URL receives `message.delivered` once it reaches the phone.

## Step 6: Finish

You've authenticated, added a customer, created a template, sent a message and received its delivery. These are
the building blocks of every Goomzo integration.

## Learn more

- [Send messages](https://docs.goomzo.africa/docs/developers/messages/send?utm_source=llms&utm_medium=ai): SMS and WhatsApp, one at a time or up to 100 together.
- [Send templates](https://docs.goomzo.africa/docs/developers/messages/templates?utm_source=llms&utm_medium=ai): your own values, and private ones.
- [WhatsApp templates](https://docs.goomzo.africa/docs/developers/templates/create?utm_source=llms&utm_medium=ai): write templates for Meta to review.
- [Webhooks](https://docs.goomzo.africa/docs/developers/webhooks?utm_source=llms&utm_medium=ai): every event, and how to check signatures.
- [Safe retries](https://docs.goomzo.africa/docs/developers/idempotency?utm_source=llms&utm_medium=ai): retry without sending twice.

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)