PyLoops

Unofficial Python SDK for Loops.so.

Installation

pip install pyloops

Or with uv:

uv add pyloops

Quick Start

PyLoops offers two ways to interact with the Loops API:

High-Level API

import pyloops

# Configure once (or set LOOPS_API_KEY environment variable)
pyloops.configure(api_key="your_api_key_here")

# Get the client
client = pyloops.get_client()

# Upsert a contact
await client.upsert_contact(
    email="user@example.com",
    first_name="John",
    last_name="Doe",
    subscribed=True,
)

# Find a contact
contacts = await client.find_contact(email="user@example.com")

# Send an event
await client.send_event(
    event_name="user_signup",
    email="user@example.com",
    event_properties={"plan": "premium"},
)

# List mailing lists
mailing_lists = await client.list_mailing_lists()

# Look up the data variables a transactional template expects, then send it
variables = await client.get_transactional_variables("clfq6dinn000yl70fgwwyp82l")
# -> ["firstName", "inviteLink"]

await client.send_transactional_email(
    transactional_id="clfq6dinn000yl70fgwwyp82l",
    email="user@example.com",
    data_variables={
        "firstName": "Jane",
        "inviteLink": "https://myapp.com/invite/abc123",
    },
)

Low-Level API

For more control, use the auto-generated low-level API directly:

from pyloops import AuthenticatedClient
from pyloops._generated.api.contacts import put_v1_contacts_update
from pyloops._generated.models import ContactUpdateRequest

# Note: the base URL must NOT include the "/v1" segment — it is now part of
# each endpoint path (e.g. /v1/contacts/update).
client = AuthenticatedClient(
    base_url="https://app.loops.so/api",
    token="your_api_key_here",
)

response = await put_v1_contacts_update.asyncio(
    client=client,
    body=ContactUpdateRequest(
        email="user@example.com",
        first_name="John",
        last_name="Doe"
    )
)

Authentication

All API calls require a Loops API key. Get your API key from your Loops account settings.

There are three ways to configure authentication:

1. Environment variable:

export LOOPS_API_KEY="your_api_key_here"

2. Module-level configuration:

import pyloops
pyloops.configure(api_key="your_api_key_here")

3. Per-client configuration:

import pyloops
client = pyloops.LoopsClient(api_key="your_api_key_here")

Features

The high-level LoopsClient wraps every Loops.so API endpoint:

• Contacts: Create, upsert, find, and delete contacts
• Contact Properties: List and create custom contact properties
• Contact Suppression: Read and remove suppression status
• Mailing Lists: View available mailing lists
• Events: Trigger event-based emails
• Event Patterns: List and look up triggerable event types
• Transactional Emails: Send, list, and manage transactional templates (create, update, draft, publish), and read the data variables a template expects
• Campaigns & Campaign Groups: List, get, create, and update
• Transactional Groups: List, get, create, and update
• Themes & Components: List, get, create, and update reusable branding/building blocks
• Email Messages: Get, update, preview, and run Guardian content checks
• Workflows & Workflow Nodes: Create, update, and delete workflows, change mailing lists, and build the node graph (create/update/branch/reroute/delete nodes)
• Audience Segments: List, get, and create
• Uploads: Create and complete asset uploads
• Sending IPs: Retrieve dedicated sending IP addresses

Safe Mode

When developing locally, you can enable safe mode to prevent accidentally sending emails or syncing contacts to real addresses. With safe mode enabled, only emails matching your allowed domains will be accepted — all others will raise a LoopsUnsafeEmailError.

import pyloops

pyloops.configure(
    api_key="your_api_key_here",
    safe_mode=True,
    safe_mode_allowed_domains=("@test.com", "@example.com", "@yourcompany.com"),
)

client = pyloops.get_client()

# This works
await client.send_transactional_email(
    transactional_id="welcome",
    email="dev@test.com",
)

# This raises LoopsUnsafeEmailError
await client.send_transactional_email(
    transactional_id="welcome",
    email="real-user@gmail.com",
)

You can also set it per-client:

client = pyloops.LoopsClient(
    api_key="your_api_key_here",
    safe_mode=True,
    safe_mode_allowed_domains=("@test.com",),
)

Testing

PyLoops ships a testing module that mocks all Loops API endpoints at the HTTP transport level using respx. Your real client code runs end-to-end, but no actual API requests leave the process.

Install with the testing extra:

pip install pyloops[testing]

Basic usage

import json
import pyloops
from pyloops.testing import loops_respx_mock

async def test_sends_welcome_email():
    with loops_respx_mock() as api:
        client = pyloops.get_client()
        await client.send_transactional_email(
            transactional_id="welcome",
            email="user@test.com",
            data_variables={"name": "Jan"},
        )

        # Inspect the HTTP request that pyloops made
        request = api["transactional"].calls[0].request
        body = json.loads(request.content)
        assert body["transactionalId"] == "welcome"
        assert body["email"] == "user@test.com"

Pytest fixture

import pytest
from pyloops.testing import loops_respx_mock

@pytest.fixture
def loops_api():
    with loops_respx_mock() as router:
        yield router

async def test_create_contact(loops_api):
    client = pyloops.get_client()
    result = await client.create_contact(email="new@test.com")
    assert result.success is True
    assert loops_api["create_contact"].called

Simulating errors

Override any route to return custom responses:

from httpx import Response

async def test_handles_rate_limit(loops_api):
    loops_api["transactional"].mock(
        return_value=Response(
            429,
            json={"success": False},
            headers={"x-ratelimit-limit": "10", "x-ratelimit-remaining": "0"},
        )
    )
    client = pyloops.get_client()
    with pytest.raises(pyloops.LoopsRateLimitError):
        await client.send_transactional_email(transactional_id="abc", email="user@test.com")

Available mock routes

Every Loops endpoint the client supports has a matching mock route, accessible by name on the yielded router. Route names mirror the client method names, so a call to client.create_workflow(...) is recorded under api["create_workflow"]. Common routes:

Additional families are mocked too — campaigns, campaign/transactional groups, transactional templates, themes, components, email messages (incl. preview and Guardian), uploads, audience segments, event patterns, and workflows/workflow nodes. See EXPECTED_ROUTE_NAMES in tests/test_testing.py for the full list.

Testing with safe mode

The mock disables safe mode by default. To test safe mode behavior, pass safe_mode=True and your allowed domains:

with loops_respx_mock(safe_mode=True, safe_mode_allowed_domains=("@test.com",)) as api:
    client = pyloops.get_client()
    await client.send_transactional_email(transactional_id="t1", email="dev@test.com")  # OK
    await client.send_transactional_email(transactional_id="t1", email="user@gmail.com")  # raises

Documentation

For detailed API documentation, visit the Loops.so API docs.

Automated Updates

This SDK is automatically updated to match the latest Loops.so API specification. The package version corresponds to the Loops API version (current: 1.21.12). A three-segment version (e.g. 1.21.2) tracks the Loops API version directly; a fourth segment (e.g. 1.21.2.1) denotes a client-wrapper release built on top of that API version and is assigned automatically at publish time.

A GitHub Action checks for API updates daily and creates a pull request when changes are detected. After review and merge, a new version is automatically published to PyPI. A merge that leaves the shipped code untouched - docs or tests only - publishes nothing.

Development

Setup

# Clone the repository
git clone https://github.com/doctorgpt-corp/pyloops.git
cd pyloops

# Install dependencies with uv
uv sync --all-groups

Running Tests

Using just:

just check      # Run linting + type checking
just lint       # Run linting only
just typecheck  # Run type checking only
just fmt        # Format code

Or directly with uv:

uv run ruff check src/
uv run pyright src/

Project Structure

src/pyloops/
├── __init__.py          # Main exports
├── client.py            # High-level LoopsClient wrapper
├── config.py            # Configuration
├── exceptions.py        # Exceptions
├── api/                 # Re-exports from _generated.api
├── models/              # Re-exports from _generated.models
└── _generated/          # ALL auto-generated code
    ├── client.py
    ├── api/
    ├── models/
    └── types.py

Regenerate SDK

To manually regenerate the SDK from the latest OpenAPI spec:

just generate

Or manually:

rm -rf src/pyloops/_generated
uv tool run openapi-python-client generate --url https://app.loops.so/openapi.yaml --meta uv
mv loops-open-api-spec-client/loops_open_api_spec_client src/pyloops/_generated
rm -rf loops-open-api-spec-client openapi.yaml

Custom code is never touched during regeneration.

License

MIT

Disclaimer

This is an unofficial SDK and is not affiliated with or endorsed by Loops.so.