Send emails, manage contacts, and trigger events with Loops — the email platform for SaaS.
# 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
- manage contact suppression status/removal
- create draft campaigns, update email-message content (subject, sender, LMX), and upload image assets
- list themes and components to build LMX payloads
- 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. 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, transactional payloads, uploads, SDK examples, and HTTP errors:
Read `references/http-api.md`
- Campaigns, email messages, themes, and components:
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# 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 or inspect 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, and LMX file flags:
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`# 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# 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. 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.
4. Validate nesting and content-type rules before producing output (see spec section 3).
5. Check the common-mistakes table in the spec before finalizing output.
6. 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`
- 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.
## 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 `&`, `<` as `<`, and `"` in attributes as `"`
- [ ] 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>`
- [ ] 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 are intentional: supplied by `themeId` or explicit `bodyColor`/`backgroundColor`
- [ ] 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
- [ ] 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
- [ ] Adjacent `<Section>` siblings are separated with a line-break spacer unless the user explicitly specifies a different section-spacing approach
- [ ] `<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