loops-so
Unofficial Rust SDK for Loops.so.
The Rust counterpart of pyloops: the same two-layer design, safe mode, test mock and automated update flow.
Installation
The client is async and runs on tokio through reqwest.
TLS uses rustls by default; enable native-tls instead with
default-features = false, features = ["native-tls"].
Quick Start
loops-so offers two ways to interact with the Loops API.
High-Level API
use ;
// Configure once (or set the LOOPS_API_KEY environment variable)
configure;
// Get the client
let client = get_client?;
// Upsert a contact
client
.upsert_contact
.await?;
// Find a contact
let contacts = client.find_contact.await?;
// Send an event
client
.send_event
.await?;
// List mailing lists
let mailing_lists = client.list_mailing_lists.await?;
// Look up the data variables a transactional template expects, then send it
let variables = client.get_transactional_variables.await?;
// -> ["firstName", "inviteLink"]
client
.send_transactional_email
.await?;
Failures come back as LoopsError:
Api (with the status and the message Loops sent), RateLimit (with the
x-ratelimit-* headers), ContactExists, UnsafeEmail, InvalidInput,
Configuration, Http and Decode.
Low-Level API
For more control, use the client generated from the OpenAPI spec directly. It shares the high-level client's base URL and API key:
use ;
let client = builder.api_key.build?;
let low_level = client.low_level?;
let response = low_level
.update_contact
.await?;
The request and response models live in loops_so::generated and are what the
high-level methods return.
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:
-
Environment variable:
-
Process-wide configuration:
configure; let client = get_client?; -
Per-client configuration:
let client = builder.api_key.build?;
LoopsClient::builder() also takes a base_url and a preconfigured
reqwest::Client (for timeouts or a proxy). Every setting left unset falls back
to configure().
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
- Workflow 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
- Metrics: Campaign, transactional template and workflow email node metrics
- 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 fail with LoopsError::UnsafeEmail before any request is sent. Safe mode checks the addresses a call carries: a call that identifies the contact only by user ID (e.g. send_event with ContactId::user_id) has no address to check and goes through, as in pyloops.
use ;
configure;
let client = get_client?;
// This works
client.send_transactional_email.await?;
// This fails with LoopsError::UnsafeEmail
let blocked = client
.send_transactional_email
.await;
assert!;
You can also set it per client:
let client = builder
.api_key
.safe_mode
.safe_mode_allowed_domains
.build?;
Testing
loops-so ships a testing module that mocks every Loops API endpoint with a
local wiremock server. Your real client code runs
end-to-end, but no actual API request leaves the process.
Enable the testing feature for your tests:
[]
= { = "0.1", = ["testing"] }
Basic usage
use Route;
use LoopsMock;
use TransactionalOptions;
async
LoopsMock::start() configures the process-wide client to use the mock, resets
the get_client() singleton, and holds a lock so tests using it run one at a
time. Dropping it resets the singleton and restores the previous configuration.
mock.client() gives a client bound to the mock without touching the singleton.
Simulating errors
Override any route to return custom responses:
use ResponseTemplate;
async
mock.respond_json(route, status, body) is a shorthand for JSON bodies; the
latest override of a route wins and mock.reset_route(route) restores the
default. A request to an unmocked path gets a 501 naming the method and path.
Available mock routes
Every Loops endpoint the client supports has a matching Route, named after
the client method that calls it, so a call to client.create_workflow(...) is
recorded under Route::CreateWorkflow. Route::from_name("create_workflow")
looks one up by its snake-case name. Common routes:
| Route | Method | Endpoint |
|---|---|---|
Health |
GET | /v1/api-key |
Transactional |
POST | /v1/transactional |
ListTransactional |
GET | /v1/transactional |
CreateContact |
POST | /v1/contacts/create |
UpsertContact |
PUT | /v1/contacts/update |
FindContact |
GET | /v1/contacts/find |
DeleteContact |
POST | /v1/contacts/delete |
ListContactProperties |
GET | /v1/contacts/properties |
CreateContactProperty |
POST | /v1/contacts/properties |
SendEvent |
POST | /v1/events/send |
ListMailingLists |
GET | /v1/lists |
ListSendingIps |
GET | /v1/dedicated-sending-ips |
Additional families are mocked too — campaigns, campaign/transactional/workflow groups,
transactional templates, themes, components, email messages (incl. preview and
Guardian), uploads, audience segments, event patterns, metrics, and
workflows/workflow nodes. See Route::ALL for the full list.
Testing with safe mode
The mock disables safe mode by default. To test safe mode behavior, turn it on with your allowed domains:
let _mock = builder
.safe_mode
.safe_mode_allowed_domains
.start
.await;
Documentation
API reference: docs.rs/loops-so. For the Loops API itself, see the Loops.so API docs.
Automated Updates
This SDK is automatically updated to match the latest Loops.so API specification (current: 1.22.6, also exposed as loops_so::LOOPS_API_VERSION).
The crate follows semver below 1.0: a release built on a new Loops API version
bumps the minor version (regenerated models usually change shape, which is
breaking in Rust), as does a breaking change to the hand-written client. Other
releases bump the patch version. Depend on loops-so = "0.x" to get compatible
fixes without picking up a new API version unannounced.
A GitHub Action checks for API updates daily and opens a pull request when changes are detected. After review and merge, a new version is automatically published to crates.io. A merge that leaves the shipped code untouched - docs or tests only - publishes nothing.
Development
Setup
# The pinned toolchain (rust-toolchain.toml) installs on first use.
# Install the pinned code generator:
Running checks
Project Structure
src/
├── lib.rs # Public exports
├── client/ # High-level LoopsClient, one file per endpoint family
├── config.rs # configure() / get_config()
├── error.rs # LoopsError
├── responses.rs # Hand-written response models
├── routes.rs # The named route table (client, mock, spec test)
├── spec.rs # LOOPS_API_VERSION, OPENAPI_SPEC, openapi_spec_path()
├── testing.rs # LoopsMock (feature "testing")
├── openapi.yaml # The Loops OpenAPI spec generated/ was built from
└── generated/ # ALL auto-generated code (oas3-gen)
├── mod.rs
├── client.rs
└── types.rs
xtask/ # Spec normalizer run before the generator
Regenerate SDK
To fetch the latest OpenAPI spec, regenerate, and run all checks:
To regenerate from the committed src/openapi.yaml only:
Regeneration runs cargo xtask normalize-spec to work around oas3-gen
limitations (OpenAPI 3.1 nullable types, implicit discriminator mappings, and
closed objects that would reject fields Loops adds), then the pinned
oas3-gen, then cargo fmt. Custom code is never touched, and CI fails if src/generated/
differs from what the generator produces.
The spec ships with the crate
The Loops OpenAPI spec the client was generated from is committed as
src/openapi.yaml and included in the published crate, so a consumer can check
its own fakes or contract tests against exactly the API the installed client
speaks:
let yaml: &str = OPENAPI_SPEC;
let path: &Path = openapi_spec_path;
License
MIT
Disclaimer
This is an unofficial SDK and is not affiliated with or endorsed by Loops.so.