loops

What this skill does

## 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:

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

### Create Contact

Write to `/tmp/loops_request.json`:

```json
{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "userId": "clerk_user_abc123",
  "subscribed": true,
  "userGroup": "free"
}
```

```bash
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`:

```json
{
  "email": "[email protected]",
  "userGroup": "pro",
  "planUpgradedAt": "2024-01-15"
}
```

```bash
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:

```bash
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`:

```json
{
  "email": "[email protected]"
}
```

```bash
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`:

```json
{
  "email": "[email protected]",
  "eventName": "signup",
  "eventProperties": {
    "planType": "free",
    "signupSource": "landing_page"
  }
}
```

```bash
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`:

```json
{
  "transactionalId": "<transactional-id>",
  "email": "[email protected]",
  "dataVariables": {
    "firstName": "Jane",
    "resetLink": "https://app.example.com/reset?token=abc123"
  }
}
```

```bash
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

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

### List Mailing Lists

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

### List Contact Properties

```bash
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.