Skip to main content

SendPulse REST API — Python SDK

Official Python client for the SendPulse REST API.

  • Python ≥ 3.11, single runtime dependency (httpx)
  • Thin transport: OAuth / API-key auth, automatic token refresh, typed exceptions
  • Chained endpoint surface with IDE autocomplete — client.crm.deals.getDeal({...})
  • Raw get/post/... fallback for any endpoint
  • Swappable HTTP client and token storage
  • Ships llms.txt for AI coding assistants · mypy strict · ruff

Installation

pip install pysendpulse
from sendpulse import Client

Quick start

API key auth

client = Client(api_key="YOUR_API_KEY")

OAuth (client credentials)

client = Client(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET")

Tokens are fetched automatically and stored on disk between requests. A 401 is retried once with a freshly minted token.

Calling endpoints

Chained surface

Mapped endpoints are reachable as a chain — service → resource → operation — with IDE autocomplete for every segment:

campaigns = client.email.campaigns.getCampaigns({"limit": 10})
campaign  = client.email.campaigns.getCampaignById({"id": 12345})

deal = client.crm.deals.getDeal({"dealId": 42})

client.smtp.emails.sendSmtpEmail({
    "email": {
        "subject": "Hello",
        "from": {"name": "Me", "email": "me@example.com"},
        "to": [{"name": "You", "email": "you@example.com"}],
        "html": "<p>Hi!</p>",
    },
})

You pass one dict. Path params ({id}) and declared query params are routed automatically; any other key goes to the JSON body (for a GET it becomes a query param). Every call returns the decoded JSON response (a dict or list; empty body → {}), or raises one of the exceptions below.

Hyphenated services (file-manager, live-chat, viber-chatbot, web-push) are not valid attribute names — reach them via getattr: getattr(client, "file-manager").directory.getDirectoryTree({}).

The full list of chains, paths and parameters lives in sendpulse/resources/operations/ and is mirrored in llms.txt.

Raw requests

For any endpoint not in the map — or when you want full control — call a path directly:

client.get("/campaigns", {"limit": 10})            # also query params
client.post("/smtp/emails", {"email": {}})          # put / patch / delete too

# lowest level:
client.request("GET", "/campaigns")
from sendpulse.http.request import Request
client.send(Request(method="GET", uri="/campaigns"))

IDE autocomplete

The chained surface is powered by generated stub definitions in sendpulse/stubs.pyi:

  • PyCharm / VS Code (Pylance) index the .pyi automatically — no setup.
  • mypy resolves the chain and flags unknown resources/methods and missing required params. Each operation's HTTP route and parameter list is in its docstring (shown on hover).

Error handling

from sendpulse import (
    Client,
    AuthException,       # 401 / 403 — wrong credentials or insufficient permissions
    RateLimitException,  # 429 — too many requests
    ApiException,        # any other 4xx / 5xx from the API
    NetworkException,    # connection timeout, DNS failure, etc.
    ProtocolException,   # response received but could not be parsed (malformed JSON)
)

try:
    campaigns = client.email.campaigns.getCampaigns()
except AuthException as e:
    print(e.http_status, e.raw_body)   # 401 / 403 — credentials problem
except RateLimitException:
    ...                                # 429 — back off and retry
except ApiException as e:
    print(e.http_status, e.raw_body)   # other 4xx / 5xx
except ProtocolException as e:
    ...                                # unexpected response format
except NetworkException as e:
    ...                                # transport error

All SDK exceptions subclass sendpulse.SendPulseError, so a single except SendPulseError covers every SDK error.

Configuration

client = Client(
    api_key="key",
    connect_timeout=10.0,   # seconds, default
    request_timeout=30.0,   # seconds, default
)

Custom HTTP client

Any object that implements send(request: Request) -> Response is accepted:

from sendpulse.http.request import Request
from sendpulse.http.response import Response

class MyHttpClient:
    def send(self, request: Request) -> Response:
        ...

client = Client(api_key="key", http_client=MyHttpClient())

Custom token storage

from sendpulse.auth.token_storage import InMemoryTokenStorage

# In-memory (tokens lost on process exit — useful for tests)
client = Client(
    client_id="id",
    client_secret="secret",
    token_storage=InMemoryTokenStorage(),
)

Default is FileTokenStorage (system temp directory or custom cache_dir).

Context manager

Use Client as a context manager to release the underlying HTTP connection:

with Client(api_key="YOUR_API_KEY") as client:
    lists = client.email.mailingLists.getMailingLists()

Documentation

Topic
Authentication & token storage docs/authentication.md
Exception reference docs/exceptions.md
Testing docs/testing.md
FastAPI integration docs/fastapi.md
Architecture & decisions docs/architecture.md
AI assistants llms.txt

License

MIT

Metadata

Release files for pysendpulse 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pysendpulse 2.0.1
File Size Uploaded Provenance Actions
pysendpulse-2.0.1.tar.gz 65.0 kB With provenance Details for pysendpulse-2.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pysendpulse 2.0.1
File Interpreter ABI Platform Actions
pysendpulse-2.0.1-py3-none-any.whl Python 3 none any Details for pysendpulse-2.0.1-py3-none-any.whl

Total release size: 121.7 kB

Release files / pysendpulse-2.0.1.tar.gz

Download URL pysendpulse-2.0.1.tar.gz
Size 65.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f8b6340fad155e0ca40928b28b4a91c7e3df256377f4d0ba83fd404c1346e7c6
BLAKE2b-256 checksum
How to use checksums
692e5bb52273d0423c5a2aae9784ebf9b9933668e281e8b0487f812b20975d08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / pysendpulse-2.0.1-py3-none-any.whl

Download URL pysendpulse-2.0.1-py3-none-any.whl
Size 56.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5b0c1bcd41783c2b1d2b4f47cdf6c6b0b72c3e7c9880d6a0b46a33a063fbc437
BLAKE2b-256 checksum
How to use checksums
ce98cde1ce5b87bdd69636e1adc6f36e50359e8ee2949f316f84bd0dec0f86eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for pysendpulse 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pysendpulse-2.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page