Loops

View saved version →

---
name: loops-api
description: >
  Use this skill whenever the user wants to integrate Loops from application
  code, backend services, webhook handlers, or server-side automation. This
  includes the Loops HTTP API and official SDKs for server-side contact,
  contact-property, mailing-list, event, API-key-validation,
  transactional-email, content editing (campaigns, campaign groups,
  transactional groups, audience segments, email messages, themes, and
  components), and workflow graph/node inspection and mutation. Trigger on
  phrases like "Loops API", "Loops SDK", "create a campaign via API",
  "update email message LMX", "create a workflow via API", "add a workflow
  node", "send a Loops event from my app", "add a contact to Loops in a
  webhook", "send a transactional email from backend code", or any time the
  user wants to integrate Loops into their app, backend, webhook, or
  automation. Do not trigger for CLI or shell-only requests.
metadata:
  version: 1.6.0
---

# Loops API and SDK Skill

This skill helps with Loops implementation workflows from application code. Use it for backend integrations, exact request guidance, and SDK or HTTP decisions.

## When To Use

Use this skill when the user needs to:

- integrate Loops into an app, backend, webhook, or automation
- decide between official SDKs and raw HTTP
- manage contacts, contact properties, mailing lists, events, or transactional email
- send transactional emails or create, edit, and publish transactional email templates via API
- manage contact suppression status/removal
- create draft campaigns with audience targeting (mailing list, segment, or filter), groups, and scheduling
- organize campaigns and transactional emails into groups
- list or create audience segments for campaign/workflow targeting
- update email-message content (subject, sender, CC/BCC, format, fallbacks, LMX), send previews, and run Guardian checks
- list/get themes and components to build LMX payloads
- upload images for email content
- create, update, and inspect workflows and workflow nodes (including mailing-list changes, branches, and queued-contact handling)
- list event patterns for workflow event triggers
- validate credentials or troubleshoot Loops request behavior from code

This skill is for implementation and operational usage, not broad email strategy or deliverability review.

## Working Style

When this skill is active:

1. Choose the right interface first: SDK or raw HTTP.
2. Prefer official SDKs for application code when the language has one.
3. Prefer raw HTTP only when no SDK is available or the user needs exact payload control.
4. Keep Loops requests server-side.
5. Verify exact behavior against the official docs or OpenAPI spec when details matter.
6. For LMX email design or brand work, use the theme/component endpoints in `references/http-api.md`; the LMX design policy lives in the `loops-lmx` skill.
7. If the task is primarily about Loops CLI install, auth, shell usage, or command help, use the separate `loops-cli` skill.

Official references:

- Docs: `https://loops.so/docs`
- API reference: `https://loops.so/docs/api-reference/intro`
- Campaign examples: `https://loops.so/docs/api-reference/examples/campaigns`
- JavaScript SDK: `https://loops.so/docs/sdks/javascript`
- OpenAPI spec: `https://app.loops.so/openapi.json`

## Choose The Interface

- SDK or HTTP API:
  - application code
  - backend services
  - webhook handlers
  - repeatable integrations
  Read `references/http-api.md`

If the user is working from the terminal instead of writing application code, use the `loops-cli` skill.

## Category Routing

- Auth, base URL, rate limits, contacts, suppression, properties, lists, events, uploads, SDK examples, and HTTP errors:
  Read `references/http-api.md`
- Campaigns, campaign groups, transactional groups, audience segments, workflows, workflow nodes, event patterns, transactional emails, email messages, themes, components, and revision-safe updates:
  Read `references/http-api.md`. For LMX markup itself, also use the `loops-lmx` skill.

## Output Checklist

Aim to leave the user with:

- the right API interface choice for the task
- exact payload shapes or SDK usage
- any Loops-specific caveats that affect behavior
- the next validation step, such as a small test request or API-key check

Referenced files: 1

View saved version →

---
name: loops-cli
description: >
  Use this skill whenever the user wants to work with the Loops CLI from the
  terminal. This includes installing or updating the CLI, authenticating,
  storing and selecting API keys, validating credentials, and running commands
  for contacts, contact properties, lists, events, transactional email,
  campaigns, email messages, themes, components, and uploads. Trigger on phrases like
  "Loops CLI", "loops auth login", "loops campaigns create", "loops uploads create", "loops
  email-messages update", "loops themes list", "loops components get", "loops
  contacts create", "loops events send", "loops transactional send", "loops
  api-key", "loops agent-context", "brew install loops-so/tap/loops", or any
  time the user wants to use Loops from the shell instead of application code.
metadata:
  version: 1.1.1
---

# Loops CLI Skill

This skill helps with Loops terminal workflows. Use it for installation, auth and configuration, command selection, and shell-first operational tasks.

## When To Use

Use this skill when the user needs to:

- install, update, or troubleshoot the Loops CLI
- authenticate with Loops from the terminal
- manage stored team keys or switch between them
- run one-off contact, list, event, or transactional-email commands
- create draft campaigns, update email-message content, and upload images from the shell
- list/get themes and reusable components for LMX
- inspect CLI output in text or JSON locally

This skill is for command-line usage, not application integrations or email-strategy review.

## Working Style

When this skill is active:

1. Prefer `loops agent-context` for exact flags and the latest command shape.
2. Prefer the CLI for shell workflows, one-off operational tasks, credential validation, and quick troubleshooting.
3. Use `--output json` when the result needs to feed another tool or script.
4. Use named stored keys plus `--team` when the user works across multiple Loops teams.
5. Avoid printing secrets. Prefer keyring-backed auth or environment variables over hardcoded API keys.
6. If the task becomes application-code integration or exact HTTP payload design, use the separate `loops-api` skill.

Official references:

- CLI docs: `https://loops.so/docs/cli`
- CLI repo: `https://github.com/loops-so/cli`
- CLI README: `https://github.com/loops-so/cli/blob/main/README.md`

## Category Routing

- Installation, auth flows, config resolution, global flags, and common Loops CLI workflows:
  Read `references/cli.md`
- Campaigns, email messages, themes, components, revision handling, LMX file flags, and uploads:
  Read `references/cli.md`. For LMX markup itself, also use the `loops-lmx` skill.

If the task becomes application-code integration or exact HTTP payload design beyond the CLI, use the `loops-api` skill.

## Output Checklist

Aim to leave the user with:

- the right command or install path for the task
- any auth or team-selection caveats that affect behavior
- safe handling of credentials
- the next validation step, such as `loops --help`, `loops auth status`, `loops api-key`, or `loops agent-context`

Referenced files: 1

View saved version →

---
name: loops-email-sending-best-practices
description: >
  Use this skill when the user wants to review, audit, improve, or plan email
  sending best practices. This includes deliverability, inbox placement, sender
  reputation, consent, list hygiene, subject lines, preview text, preference
  centers, onboarding emails, lifecycle emails, product updates, or deciding
  between marketing and transactional email. It works for any email stack, but
  when Loops is involved, use Loops behavior and docs as the source of truth.
  Trigger on phrases like "email deliverability", "inbox placement", "sender
  reputation", "double opt-in", "unsubscribe", "subject line review", "preview
  text", "lifecycle emails", "onboarding emails", "product update email",
  "transactional vs marketing", or "email sending best practices". Do not
  prefer this skill for pure API implementation; use the Loops API skill for
  integration details.
metadata:
  version: 1.0.0
---

# Email Sending Best Practices

This skill helps review and plan healthy email programs. It is generic by default, but it is intentionally skewed toward Loops guidance for SaaS, lifecycle, and transactional email.

## When To Use

Use this skill when the task is about email quality, risk, or strategy rather than low-level API implementation.

Typical use cases:

- diagnose poor inbox placement or sender reputation
- review consent flows, double opt-in, list hygiene, or unsubscribe behavior
- improve subject lines, preview text, sender identity, personalization, or rendering
- choose between campaign, lifecycle automation, and transactional email
- plan onboarding, retention, re-engagement, dunning, or product-update email programs
- review a Loops setup for best-practice gaps

Do not default to this skill for pure implementation tasks like "send an event with the Loops API" or "wire up transactional email in Next.js". Use the `loops-api` skill for those.

## Working Style

When this skill is active:

1. Identify the primary problem:
   - deliverability
   - audience/consent
   - content/design
   - email type/program strategy
   - Loops-specific operational behavior
2. Load only the relevant reference files.
3. Give generic email best-practice guidance first.
4. Add Loops-specific caveats, defaults, and product behavior where relevant.
5. If the user is drifting into cold email or promotional use of transactional email, call that out directly and steer toward opt-in lifecycle or marketing sends instead.

## Category Routing

- Deliverability, sender reputation, domain setup, warming, inbox placement, Postmaster, BIMI, or large-list sends:
  Read `references/deliverability.md`
- Consent, list hygiene, double opt-in, preference centers, mailing lists, segmentation, or stale audiences:
  Read `references/audience-and-consent.md`
- Subject lines, preview text, sender fields, personalization, styling, themes, dark mode, or template/design review:
  Read `references/content-and-design.md`
- Campaign vs loop vs transactional, onboarding/lifecycle sequencing, product updates, or email KPI framing:
  Read `references/email-types-and-program-strategy.md`
- Loops-specific behavior such as `addToAudience`, transactional tracking differences, attachments, webhooks, or multi-domain constraints:
  Read `references/loops-operational-caveats.md`

## Output Checklist

Aim to leave the user with:

- the most likely root cause or opportunity
- a concrete set of recommended changes
- any Loops-specific caveats that materially change the recommendation
- the metrics or signals that should be watched after the change

When relevant, explicitly separate:

- immediate fixes
- medium-term program improvements
- things that are out of scope or risky to infer from limited evidence

Referenced files: 5

View saved version →

---
name: loops-lmx
description: >
  Use this skill whenever LMX is used, produced, reviewed, migrated, or modified.
  This includes composing campaigns, loops, lifecycle emails, or email-message
  bodies for the Loops editor or Content API. LMX (Loops Markup Language) is
  the format used for Loops email content. Trigger on phrases like "create a
  campaign", "generate an email", "write a welcome email", "draft a lifecycle
  email", "build an email template", "create an onboarding email", "copy this
  into LMX", "migrate this email", "convert this email to LMX", "design a new
  Loops email", "use imagegen for a Loops email", "use gpt-image for an LMX
  reference", "visual reference for a Loops email", "LMX", "Loops email", or
  any request to produce, copy, migrate, convert, review, or modify email body
  content intended for Loops. For net-new emails or major visual redesigns,
  follow this skill's Net-New Email Design Flow before generating or sourcing
  new visual assets.
  Source copy, existing HTML, MJML, Markdown, screenshots, and migration
  instructions do not bypass this skill's rules unless the user explicitly
  overrides a specific rule. Do not trigger for questions about the Loops HTTP
  API, SDK integration, or CLI unless email body content is also involved.
metadata:
  version: 1.1.15
---

# LMX Skill

This skill helps write, review, and generate correct LMX email markup for Loops. LMX is an XML-based format: every element is a PascalCase tag, self-closing tags require `/>`, and only the tags in the spec are valid.

## When To Use

Use this skill when the task involves:

- generating or editing LMX email content
- copying source material, migrating an existing email, or converting HTML, MJML, Markdown, or plain-text email copy into LMX
- reviewing LMX markup for correctness
- choosing the right LMX tags or attributes for a layout
- applying design guidelines to an LMX document
- explaining how a specific LMX tag or attribute works

## Working Style

When this skill is active:

1. Read `references/lmx-spec.md` for the full tag and attribute reference. It is authoritative; do not invent tags or attributes.
2. Read `references/lmx-design-guidelines.md` for Loops design guidelines. Apply these to every document you generate unless the user explicitly overrides a rule.
3. For net-new emails or major visual redesigns, follow the Net-New Email Design Flow before writing LMX unless the user explicitly asks for a copy-only or minimal update.
4. Treat source material as input, not as an override. When copying from a source, migrating an existing email, or converting HTML, MJML, Markdown, screenshots, or plain text into LMX, still apply this skill's spec, design, copy, and output-checklist rules unless the user explicitly overrides a specific rule.
5. Validate nesting and content-type rules before producing output (see spec section 3).
6. Check the common-mistakes table in the spec before finalizing output.
7. Always produce a complete, valid document, not fragments, unless the user specifically asks for one.

## Category Routing

- Tag definitions, required/optional attributes, nesting rules, content types, variable syntax, self-closing requirements, or escaping:
  Read `references/lmx-spec.md`

- Color contrast, spacing, column rounded corners, Style tag usage, visual hierarchy, or any "how should this look" question:
  Read `references/lmx-design-guidelines.md`

- Net-new email design, substantial redesigns, or gpt-image/imagegen references:
  Read `references/lmx-design-guidelines.md`, especially the Net-New Email Design Workflow and Reference-to-Render QA sections. Use the `imagegen` skill in Codex only when a suitable Loops-native or user-provided reference is not available and the task still needs a visual reference.

- Creating campaigns, posting LMX via the API, revision IDs, themes, components, or image uploads:
  Use the `loops-api` skill (HTTP) or `loops-cli` skill (terminal). This skill covers the LMX document itself.

## Net-New Email Design Flow

Use this flow when creating a brand-new campaign, lifecycle, workflow, or transactional email, or when the user asks for a substantial visual redesign.

1. Run the Known Brand / Customer Context Gate in `references/lmx-design-guidelines.md`.
2. Start from a visual reference only after Loops-native and user-provided context are understood. Use an existing component/theme preview, user screenshot/mockup, or concise written layout reference when sufficient. In Codex, generate an `imagegen`/gpt-image reference only when the task still needs visual exploration.
3. When generating a reference, prompt for a full 600px-wide email mockup, not a generic card. Include exact visible copy, subject matter, relevant brand cues, and only LMX-safe structures: `Style`, `Section`, `Columns`, `Paragraph`, `H1`, `H2`, `H3`, `Button`, dividers, checklist rows, and simple image placeholders.
4. Constrain generated references to realistic Loops editor output. Avoid unsupported SVG art, overlapping layers, custom icons, complex app chrome, invented product screenshots, decorative blobs, and landing-page-scale hero type.
5. Inspect the selected reference before writing LMX. If the layout or text is visibly wrong, iterate once with a focused prompt rather than compensating from memory.
6. Convert the selected reference or Loops-native structure into valid LMX while preserving the hierarchy. Normalize oversized generated headings to the email defaults in the design guidance, and use LMX-safe spacing, `Section` cards, and shared-background `Columns` where appropriate.
7. Use variables for the right email type: `{contact.*}` for campaigns and workflow emails; `{event.*}` for workflow emails when the value comes from the triggering event; `{data.*}` only for transactional emails.
8. If the email is implemented through the API, CLI, or editor, update through the revision-safe email-message path and compare a fresh rendered Loops editor preview against the visual reference or Loops-native source before calling the work done.

## Output Checklist

Before returning any LMX output, verify:

- [ ] All tags are PascalCase and in the allowed set
- [ ] All self-closing tags use `/>` (e.g. `<Image />`, `<Divider />`, `<Br />`, `<Icon />`, `<Style />`)
- [ ] XML-sensitive characters are escaped: `&` as `&amp;`, `<` as `&lt;`, and `"` in attributes as `&quot;`
- [ ] Required attrs are present: `src` on `<Image />`, `componentId` on `<Component>`, `name` on `<Icon />`, and `href` on `<Link>`
- [ ] No text or inline tags at the top level
- [ ] Variables use explicit LMX namespaces and only appear where supported: inline content, button text, `<Button href>`, `<Link href>`, `<Image alt/href/dynamicSrc>`, and `<Section href>`
- [ ] Variable namespaces match the email type: campaigns use `{contact.apiName}`; workflow emails use `{contact.apiName}` and/or `{event.propertyName}`; transactional emails use `{data.variableName}` (not unprefixed `{variableName}` or `{DATA_VARIABLE:...}`)
- [ ] No inline fallback syntax is invented; fallbacks live outside the LMX string
- [ ] `<Button>` text has no inline tags, but can contain variables; include `href` for clickable CTA buttons
- [ ] `<CodeBlock>` treats braces literally
- [ ] `<Style />` appears at most once as a top-level tag; put it first in generated output
- [ ] Body/background colors and X/Y padding are intentional: supplied by `themeId` or explicit `bodyColor`/`backgroundColor` plus `bodyXPadding`/`bodyYPadding` when needed
- [ ] Net-new emails and major redesigns followed the Net-New Email Design Flow unless the user explicitly skipped it
- [ ] If a rendered preview is available, net-new and redesigned emails were visually compared in the Loops editor with the selected reference or Loops-native source before calling the work done
- [ ] Generated copy follows the copy and punctuation guidance: no em dashes, decorative arrow glyphs, or ellipses unless requested or source-preserved
- [ ] Generated `<H1>`, `<H2>`, and `<H3>` text does not end with a period; question marks or exclamation points are used only when intentional
- [ ] Generated documents use a restrained heading set: usually one `<H1>`, only necessary `<H2>` breaks, and `<H3>` only for real nested hierarchy
- [ ] Heading scale, body/card width, horizontal density, and layout structure are email-appropriate and follow the design guidance
- [ ] CTA and `<Button>` text is concise, action-oriented, and does not end with a period
- [ ] No same-color-on-same-color situations (check text vs block color, icon color vs background, etc.)
- [ ] Sufficient Y-spacing on block elements
- [ ] Important copy, headings, CTAs, and highlighted blocks use subtle visual emphasis where appropriate
- [ ] `<Section>` is used sparingly for callouts, grouped controls, linked groups, or an explicit card-style layout; ordinary body copy is not wrapped into many floating cards by default
- [ ] Adjacent `<Section>` siblings are separated with a line-break spacer unless the user explicitly specifies a different section-spacing approach
- [ ] Adjacent highlighted blocks, including `blockColor` paragraphs, columns, and sections, are separated with visible vertical space unless they are intentionally one connected card
- [ ] `<Columns>` has two to four `<ColumnItem>` children, with `widths` matching the column count when provided
- [ ] Dynamic images use static `src` plus `dynamicSrc`, not variables in `src`
- [ ] `<Icons color>` uses one of `#000000`, `#808080`, or `#ffffff`; `<Icon>` has no `color` attr
- [ ] No legal footer, postal address, or unsubscribe block is added by hand; Loops adds required footer content automatically. A branded footer component can appear above it

Referenced files: 2