---
title: "Python SDK"
description: "The Goomzo API for Python, sync and asyncio."
url: "https://docs.goomzo.africa/docs/developers/python-sdk"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Get started"
related:
  - /docs/developers/get-started
  - /docs/developers/ts-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.

# Python SDK

> The Goomzo API for Python, sync and asyncio.

`goomzo` is the Goomzo API for Python. It types every request and answer, retries safely, and pages through lists
for you. It works the same way with or without asyncio.

## Requirements

- Python 3.10 or later.
- An API key. See [Authentication](https://docs.goomzo.africa/docs/developers/authentication?utm_source=llms&utm_medium=ai).

## Install

```bash
pip install goomzo
```

## Make your first request

Set your API key's secret as `GOOMZO_API_KEY`, then send a message:

```python
from goomzo import Goomzo

goomzo = Goomzo()

message = goomzo.messages.send_one({
    'to': '+255712345678',
    'channel': 'sms',
    'content': {'text': 'Amina, order #1042 is ready.'},
})

print(message['id'], message['status'])
```

With asyncio, use `AsyncGoomzo` and await each call:

```python
from goomzo import AsyncGoomzo

goomzo = AsyncGoomzo()
message = await goomzo.messages.send_one({'to': '+255712345678', 'channel': 'sms', 'content': {'text': 'Hi'}})
```

## How it reads

- **Requests and answers are dicts,** with the API's own keys, exactly as in its JSON, such as `customerId` and
  `sendAt`. Each is a typed dict, so your editor completes and checks them.
- **Arguments are Python,** such as `limit=200` or `if_exists='update'`.
- **Lists of results come back as lists.** Lists that can be long come as a [page](https://docs.goomzo.africa/docs/developers/python-sdk/lists?utm_source=llms&utm_medium=ai)
  you can loop over.

## What it does for you

- **A fixed version:** it pins the API version it was written for, so a new version never changes what your code
  gets.
- **Safe retries:** network errors, `429` and `5xx` are tried again, twice by default. Every `POST` carries an
  `Idempotency-Key`, the same on each try, so nothing is done twice.
- **Errors you can act on:** a `GoomzoError` has the `status`, the `code`, the `fields` that were wrong and the
  `request_id`.

## Next steps

<Cards>
  <Card
    title="Configuration"
    href="/docs/developers/python-sdk/configuration"
    description="API key, retries, timeouts and your own HTTP client."
  />
  <Card title="Send messages" href="/docs/developers/python-sdk/messages" description="SMS and WhatsApp, one or up to 100 at once." />
  <Card title="Webhooks" href="/docs/developers/python-sdk/webhooks" description="Check that an event is from Goomzo." />
</Cards>

---

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