loops

Troubleshooting

If requests fail, run zero doctor check-connector --env-name LOOPS_TOKEN or zero doctor check-connector --url https://app.loops.so/api/v1/api-key --method GET

Core APIs

Test API Key

Verify your API key is valid:

curl -s "https://app.loops.so/api/v1/api-key" --header "Authorization: Bearer $LOOPS_TOKEN"

Create Contact

Write to /tmp/loops_request.json:

{
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "userId": "clerk_user_abc123",
  "subscribed": true,
  "userGroup": "free"
}

curl -s -X POST "https://app.loops.so/api/v1/contacts/create" --header "Authorization: Bearer $LOOPS_TOKEN" --header "Content-Type: application/json" -d @/tmp/loops_request.json

Docs: https://loops.so/docs/api-reference/create-contact

Update Contact

Write to /tmp/loops_request.json:

{
  "email": "user@example.com",
  "userGroup": "pro",
  "planUpgradedAt": "2024-01-15"
}

curl -s -X PUT "https://app.loops.so/api/v1/contacts/update" --header "Authorization: Bearer $LOOPS_TOKEN" --header "Content-Type: application/json" -d @/tmp/loops_request.json

Find Contact

Find a contact by email address. Replace <email> with the actual email:

curl -s "https://app.loops.so/api/v1/contacts/find?email=<email>" --header "Authorization: Bearer $LOOPS_TOKEN"

Delete Contact

Write to /tmp/loops_request.json:

{
  "email": "user@example.com"
}

curl -s -X DELETE "https://app.loops.so/api/v1/contacts/delete" --header "Authorization: Bearer $LOOPS_TOKEN" --header "Content-Type: application/json" -d @/tmp/loops_request.json

Send Event

Trigger an automated email loop by sending an event. Events map to loops configured in your Loops dashboard.

Write to /tmp/loops_request.json:

{
  "email": "user@example.com",
  "eventName": "signup",
  "eventProperties": {
    "planType": "free",
    "signupSource": "landing_page"
  }
}

curl -s -X POST "https://app.loops.so/api/v1/events/send" --header "Authorization: Bearer $LOOPS_TOKEN" --header "Content-Type: application/json" -d @/tmp/loops_request.json

Docs: https://loops.so/docs/api-reference/send-event

Send Transactional Email

Send a one-off email using a transactional template. Replace <transactional-id> with the ID from your Loops dashboard.

Write to /tmp/loops_request.json:

{
  "transactionalId": "<transactional-id>",
  "email": "user@example.com",
  "dataVariables": {
    "firstName": "Jane",
    "resetLink": "https://app.example.com/reset?token=abc123"
  }
}

curl -s -X POST "https://app.loops.so/api/v1/transactional" --header "Authorization: Bearer $LOOPS_TOKEN" --header "Content-Type: application/json" -d @/tmp/loops_request.json

Docs: https://loops.so/docs/api-reference/send-transactional-email

List Transactional Emails

curl -s "https://app.loops.so/api/v1/transactional" --header "Authorization: Bearer $LOOPS_TOKEN" | jq '[.[] | {id, name}]'

List Mailing Lists

curl -s "https://app.loops.so/api/v1/lists" --header "Authorization: Bearer $LOOPS_TOKEN" | jq '[.[] | {id, name}]'

List Contact Properties

curl -s "https://app.loops.so/api/v1/contacts/customFields" --header "Authorization: Bearer $LOOPS_TOKEN" | jq '[.[] | {key, label, type}]'

Guidelines

1. Contact identity: Use email as the primary identifier. Optionally pass userId (e.g., Clerk user ID) to link contacts across systems.
2. Event names: Must exactly match the event name configured in your Loops dashboard loop trigger.
3. Transactional IDs: Find the transactionalId in Loops under Transactional > [template] > API.
4. Rate limit: 10 requests per second per team. Implement exponential backoff on HTTP 429.
5. Field length: Maximum 500 characters per field value.
6. No CORS: All requests must be server-side — never expose the API key to the browser.