API Introduction

The Loops API lets you manage contacts, send events and transactional email, and create and manage campaigns, email content, themes, and workflows. Prefer a no-code or low-code setup? Use our integrations (like Zapier or Make), or trigger workflows using incoming webhooks.

To manage Loops with an AI agent, use the MCP server, or install the Loops CLI and agent skills for coding agents like Claude Code, Codex, Cursor, and OpenCode.

Authentication

Generate an API key at Settings -> API in Loops. Make sure to copy the key and keep it in a secure place. You will not be able to access it again.

Your Loops API key should never be used client side or exposed to your end users. Never commit an API key to a code repository. Save it in an environment variable or non-committed file instead.

Include your API key as a Bearer token in the Authorization header on each request. You can test your API key by making a GET request to the API key endpoint:

curl https://app.loops.so/api/v1/api-key \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

If successful, you will receive the following response:

{
  "success": true,
  "teamName": "Company name"
}

Testing and development environments

Loops doesn’t have a separate sandbox or staging environment. To keep development activity from affecting your production audience and sending reputation, create a new team for each environment. Create a new team with a new domain. If you want to use the same apex domain as your main account, get in touch with our support team. When testing, you can send to @example.com and @test.com addresses. API calls that create contacts, send events, or send transactional email will return normal success responses for these addresses, but no email will actually be delivered. This lets you exercise your integration end-to-end without affecting your sending domain’s reputation. See Testing workflows and Testing transactional emails for details.

API Reference

The base URL for the API is https://app.loops.so/api

API key

Test your API key.

Test API key

Audience segments

View audience segments for campaign targeting.

Get audience segment

List audience segments

Create audience segment

Campaign groups

Organize campaigns into groups.

Create campaign group

Update campaign group

Get campaign group

List campaign groups

Campaigns

Create and manage campaigns.

Create campaign

Update campaign

Get campaign

Get campaign metrics

List campaigns

Configuration

View configuration settings.

List dedicated sending IP addresses

Contact properties

Manage contact properties.

Create contact property

List contact properties

Contacts

Manage contacts.

Create contact

Update contact

Find contact

Delete contact

Check contact suppression status

Remove suppression for a contact

Components

Reusable components for your emails.

Create component

Update component

Get component

List components

Email messages

Manage the content of campaigns and transactional emails.

Update email message

Get email message

Send a preview email message

Render an email message as HTML

Run Guardian checks

Event patterns

View workflow event patterns.

List event patterns

Get event pattern

Get event pattern by name

Events

Send events to trigger workflows.

Send event

Mailing lists

View your mailing lists.

List mailing lists

Themes

Retrieve email themes.

Create theme

Update theme

Get theme

List themes

Transactional emails

Create, manage and send transactional emails.

Send transactional email

Create transactional email

Update transactional email

Ensure transactional email has draft

Publish transactional email

Get transactional email

Get transactional email metrics

List transactional emails

List transactional emails (legacy)

Transactional groups

Organize transactional emails into groups.

Create transactional group

Update transactional group

Get transactional group

List transactional groups

Uploads

Upload images for email messages.

Create upload

Complete upload

Workflow groups

Organize workflows into groups.

Create workflow group

Update workflow group

Get workflow group

List workflow groups

Workflow nodes

View and mutate workflow nodes.

Create workflow node

Add a branch

Update workflow node

Get workflow node

Get workflow node metrics

Reroute a node connection

Delete workflow node

Delete workflow nodes recursively

Workflows

View and manage workflows.

Create workflow

Update workflow

Get workflow

List workflows

Change workflow mailing list

Delete workflow

Rate Limiting

To ensure the quality of service for all users, our API is rate limited. This means there’s a limit to the number of requests your application can make to our API in a certain time frame. The baseline rate limit is 10 requests per second per team. For the content API, the baseline rate limit is 60 requests per 60 seconds per team. This applies to /v1/campaigns/*, /v1/campaign-groups/*, /v1/components/*, /v1/email-messages/*, /v1/themes/*, /v1/transactional-emails/*, /v1/transactional-groups/*, /v1/uploads/*, and /v1/workflows/* endpoints.

Rate Limiting Details

To see your current usage, we provide the following response headers in every API response:

x-ratelimit-limit: The maximum number of requests you can make per second.
x-ratelimit-remaining: The number of requests remaining in the current rate limit window.

Here is an example of a successful response with rate limit headers:

Example API response showing rate limit headers

If you exceed this limit, you’ll receive a response with HTTP status 429 Too Many Requests. Here is an example of a failed response with rate limit headers:

Example 429 rate limit response with headers

It’s important to handle these 429 responses in your application. We recommend implementing retries with an exponential backoff strategy.If your use case requires a higher limit, please contact support and we’ll be happy to discuss your needs.

Debugging

Sometimes things go wrong. Here are some tips to help you debug your API requests.

Debugging Steps

If you are having trouble with the API, we recommend using a tool like Postman to test your requests.

Handling CORS errors

The Loops API does not support cross-origin requests made from client-side JavaScript. To avoid CORS errors, make sure to issue your requests from a server-side application.

Dealing with `401 Unauthorized` “Invalid API key” errors

Make sure you have generated an API key from Settings -> API and that you are including it in your requests.Your API key should be included in the “Authorization” header of your request, following the format Authorization: Bearer YOUR_API_KEY.

Handling rate limiting (`429` Responses)

The Loops API allows a maximum of 10 requests per second per team. If you receive a 429 Too Many Requests response, this means you have exceeded this limit.The x-ratelimit-limit and x-ratelimit-remaining headers in the response can provide information about your current rate limit usage.

Handling other `400`-level Responses

400-level responses typically indicate that there was a problem with the request. The response body will contain more information about what went wrong, so be sure to check it for details.Check your request type (GET, POST, PUT, DELETE) and ensure that you are using the correct one for the endpoint you are trying to access.

`Some body key or value is longer than allowable`

If you receive this error, it means that a value in the request body is too long. We support a maximum of 500 characters for each value, including the opening and closing quotes. Please reduce the length of the values in your request and try again.

If you have followed these steps and are still experiencing issues, don’t hesitate to reach out to the Loops team for further assistance.

OpenAPI spec

Get started quickly with the Loops API using our OpenAPI documents. You can import these documents into an API client like Postman or Insomnia to see and use all of our endpoints, with example requests and expected responses.

YAML: app.loops.so/openapi.yaml
JSON: app.loops.so/openapi.json

SDKs

SDKs are software packages built on top of the API, making it easier to integrate into your project.

Go

The official Go SDK for Loops.

JavaScript

The official JavaScript/TypeScript SDK for Loops.

Nuxt

The official Nuxt module for Loops.

PHP

The official PHP SDK for Loops.

Ruby

The official Ruby SDK for Loops.

Unofficial SDKs

The following SDKs are community-submitted and have not been officially reviewed or endorsed by Loops. We recommend thoroughly testing and reviewing the code before integrating it into your project.

Laravel by PlutoLinks
PHP by PlutoLinks
Ruby on Rails by Daniel Friis

Submit an SDK

​Authentication

​Testing and development environments

​API Reference

​API key

Test API key

​Audience segments

Get audience segment

List audience segments

Create audience segment

​Campaign groups

Create campaign group

Update campaign group

Get campaign group

List campaign groups

​Campaigns

Create campaign

Update campaign

Get campaign

Get campaign metrics

List campaigns

​Configuration

List dedicated sending IP addresses

​Contact properties

Create contact property

List contact properties

​Contacts

Create contact

Update contact

Find contact

Delete contact

Check contact suppression status

Remove suppression for a contact

​Components

Create component

Update component

Get component

List components

​Email messages

Update email message

Get email message

Send a preview email message

Render an email message as HTML

Run Guardian checks

​Event patterns

List event patterns

Get event pattern

Get event pattern by name

​Events

Send event

​Mailing lists

List mailing lists

​Themes

Create theme

Update theme

Get theme

List themes

​Transactional emails

Send transactional email

Create transactional email

Update transactional email

Ensure transactional email has draft

Publish transactional email

Get transactional email

Get transactional email metrics

List transactional emails

List transactional emails (legacy)

​Transactional groups

Create transactional group

Update transactional group

Get transactional group

List transactional groups

​Uploads

Create upload

Complete upload

​Workflow groups

Create workflow group

Update workflow group

Get workflow group

List workflow groups

​Workflow nodes

Authentication

Testing and development environments

API Reference

API key

Audience segments

Campaign groups

Campaigns

Configuration

Contact properties

Contacts

Components

Email messages

Event patterns

Events

Mailing lists

Themes

Transactional emails

Transactional groups

Uploads

Workflow groups

Workflow nodes

Workflows

Rate Limiting

Debugging

Handling CORS errors

Dealing with `401 Unauthorized` “Invalid API key” errors

Handling rate limiting (`429` Responses)

Handling other `400`-level Responses

`Some body key or value is longer than allowable`

OpenAPI spec

SDKs

Unofficial SDKs