Merge pull request #327 from coreyhaines31/chore/sync-main-pre-v2.2.0
chore: sync development with vendor PRs landed on main (pre-v2.2.0)
This commit is contained in:
Corey Haines
@@ -1,6 +1,11 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
|
||||
# Skill install artifacts (npx skills add)
|
||||
.agents/
|
||||
.claude/
|
||||
skills-lock.json
|
||||
|
||||
# Environment variables / secrets
|
||||
.env
|
||||
.env.*
|
||||
|
||||
@@ -257,6 +257,97 @@ Before launching campaigns, ensure proper tracking and account setup.
|
||||
|
||||
---
|
||||
|
||||
## Google RSA Output Spec (mandatory when generating RSAs)
|
||||
|
||||
When the user requests Google Ads RSAs (Responsive Search Ads), output MUST comply with these platform limits and structural requirements. Do not output any RSA that violates them.
|
||||
|
||||
### Hard limits per RSA (enforce before responding)
|
||||
|
||||
- **Headlines:** exactly **15** per RSA, each **≤ 30 characters** (count characters, including spaces). Render as `1. ... (NN chars)` so the reader can verify.
|
||||
- **Descriptions:** exactly **4** per RSA, each **≤ 90 characters**.
|
||||
- **Paths:** up to 2 path fields, each **≤ 15 characters**.
|
||||
- **Final URL:** present, https.
|
||||
- **Pinning:** state any pinned positions explicitly. Default = unpinned unless user asks.
|
||||
- **Per-account guardrail:** Google enforces **3 RSAs max per ad group**. When the user asks for >3, group them by ad group.
|
||||
|
||||
### Required sidecar artifacts (always include with RSA request)
|
||||
|
||||
1. **Ad group structure**, labeled `Ad group structure:` — list each ad group with its theme, target keywords (match types), and which RSAs map to it.
|
||||
2. **Negative keyword list**, labeled `Negative keywords:` — minimum **8** entries, group-level vs campaign-level called out.
|
||||
3. **Sitelinks** (≥ 4), **Callouts** (≥ 4 ≤25 chars), **Structured snippets** if relevant.
|
||||
|
||||
### Medical / CFM compliance (when product context indicates pt-BR medical practice)
|
||||
|
||||
If `.agents/product-marketing.md` indicates a Brazilian medical practice (CFM-regulated), the following terms are **forbidden** in headlines, descriptions, sitelinks, and callouts:
|
||||
|
||||
- Superlatives: `#1`, `melhor`, `o melhor`, `melhor do brasil`, `top`, `referência`
|
||||
- Outcome promises: `garantido`, `garantia`, `cura`, `cura definitiva`, `100%`, `resultado garantido`, `livre da dor`
|
||||
- Comparative claims vs other doctors/clinics
|
||||
|
||||
Use neutral framing: `atendimento`, `consulta`, `avaliação`, `segunda opinião`, `agende sua consulta`, `tire suas dúvidas`. Geo modifier (`Porto Alegre`, `POA`, `Zona Sul POA`) required where the prompt specifies a region.
|
||||
|
||||
### Output ORDER (mandatory — emit in this order to avoid truncation)
|
||||
|
||||
1. **Ad group structure** (short)
|
||||
2. **Negative keywords** (≥8, MANDATORY — emit BEFORE RSAs so it isn't dropped if output runs long)
|
||||
3. **Sitelinks** (≥4)
|
||||
4. **Callouts** (≥4)
|
||||
5. **RSA1, RSA2, RSA3** (largest section, last — safe to truncate gracefully)
|
||||
|
||||
### Output template (mandatory shape)
|
||||
|
||||
```
|
||||
Ad group structure:
|
||||
- AG1 [theme]: keywords (match types) → RSA1, RSA2
|
||||
- AG2 [theme]: ...
|
||||
|
||||
Negative keywords:
|
||||
Campaign-level:
|
||||
- <kw>
|
||||
- <kw>
|
||||
(≥4 here)
|
||||
Ad-group level:
|
||||
- AG1: <kw>, <kw>
|
||||
- AG2: <kw>, <kw>
|
||||
(≥4 more here — TOTAL ≥8 entries)
|
||||
|
||||
Sitelinks (≥4):
|
||||
- <title (≤25)> | <desc1 (≤35)> | <desc2 (≤35)> | URL
|
||||
|
||||
Callouts (≥4, each ≤25 chars):
|
||||
- <callout>
|
||||
|
||||
RSA1 — [ad group name]
|
||||
Final URL: https://...
|
||||
Path1: ... Path2: ...
|
||||
Headlines (15, each ≤30 chars):
|
||||
1. <headline> (NN chars)
|
||||
...
|
||||
15. <headline> (NN chars)
|
||||
Descriptions (4, each ≤90 chars):
|
||||
1. <description> (NN chars)
|
||||
...
|
||||
4. <description> (NN chars)
|
||||
Pinning: H1=none; H2=none; ... (or explicit pins)
|
||||
|
||||
RSA2 — ...
|
||||
RSA3 — ...
|
||||
```
|
||||
|
||||
### Self-check before responding
|
||||
|
||||
Before sending the output, run this checklist mentally:
|
||||
|
||||
- [ ] Each RSA has exactly 15 headlines, exactly 4 descriptions.
|
||||
- [ ] Every headline is ≤30 chars; every description is ≤90 chars. Character counts printed.
|
||||
- [ ] Negative keyword list labeled and ≥8 entries.
|
||||
- [ ] Ad group structure labeled.
|
||||
- [ ] If medical (CFM): no forbidden superlative/outcome words; geo modifier present where required; language is pt-BR.
|
||||
|
||||
If any check fails, rewrite before responding. Do not ship partial RSAs.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Strategy
|
||||
|
||||
+3
-1
@@ -47,6 +47,7 @@ Quick reference for AI agents to discover tool capabilities and integration meth
|
||||
| customer-io | Email | ✓ | - | [✓](clis/customer-io.js) | ✓ | [customer-io.md](integrations/customer-io.md) |
|
||||
| sendgrid | Email | ✓ | - | [✓](clis/sendgrid.js) | ✓ | [sendgrid.md](integrations/sendgrid.md) |
|
||||
| resend | Email | ✓ | ✓ | [✓](clis/resend.js) | ✓ | [resend.md](integrations/resend.md) |
|
||||
| sequenzy | Email | ✓ | ✓ | ✓ | - | [sequenzy.md](integrations/sequenzy.md) |
|
||||
| nitrosend | Email | ✓ | ✓ | - | - | [nitrosend.md](integrations/nitrosend.md) |
|
||||
| kit | Email | ✓ | - | [✓](clis/kit.js) | ✓ | [kit.md](integrations/kit.md) |
|
||||
| beehiiv | Newsletter | ✓ | - | [✓](clis/beehiiv.js) | - | [beehiiv.md](integrations/beehiiv.md) |
|
||||
@@ -189,6 +190,7 @@ Email marketing, transactional email, and automation platforms.
|
||||
| **customer-io** | Behavior-based messaging | - |
|
||||
| **sendgrid** | Transactional email at scale | - |
|
||||
| **resend** | Developer-friendly transactional | ✓ |
|
||||
| **sequenzy** | Lifecycle email, sequences, transactional email | ✓ |
|
||||
| **kit** | Creator/newsletter focused | - |
|
||||
| **beehiiv** | Newsletter platform | - |
|
||||
| **klaviyo** | E-commerce email + SMS | - |
|
||||
@@ -196,7 +198,7 @@ Email marketing, transactional email, and automation platforms.
|
||||
| **brevo** | Email + SMS, popular in EU | - |
|
||||
| **activecampaign** | Email automation + CRM | - |
|
||||
|
||||
**Agent recommendation**: Resend for transactional (dev-friendly). Postmark for deliverability. Customer.io for advanced automation. Kit for creators. Beehiiv for newsletters. Klaviyo for e-commerce email/SMS. ActiveCampaign for email + CRM combo.
|
||||
**Agent recommendation**: Resend for transactional (dev-friendly). Sequenzy for lifecycle email, sequences, and agent-driven email marketing. Postmark for deliverability. Customer.io for advanced automation. Kit for creators. Beehiiv for newsletters. Klaviyo for e-commerce email/SMS. ActiveCampaign for email + CRM combo.
|
||||
|
||||
### SMS / Messaging
|
||||
|
||||
|
||||
@@ -0,0 +1,306 @@
|
||||
# Sequenzy
|
||||
|
||||
Email marketing platform for lifecycle campaigns, automation sequences, subscriber management, transactional email, and analytics.
|
||||
|
||||
## Capabilities
|
||||
|
||||
| Integration | Available | Notes |
|
||||
|-------------|-----------|-------|
|
||||
| API | ✓ | REST API for subscribers, tags, events, campaigns, sequences, templates, transactional email, analytics, and webhooks |
|
||||
| MCP | ✓ | `@sequenzy/mcp` stdio server for agent clients |
|
||||
| CLI | ✓ | `@sequenzy/cli` for subscriber operations, transactional sends, and stats |
|
||||
| SDK | - | Use the REST API directly |
|
||||
|
||||
## Authentication
|
||||
|
||||
- **Type**: API Key
|
||||
- **Header**: `Authorization: Bearer ***`
|
||||
- **Base URL**: `https://api.sequenzy.com/api/v1`
|
||||
- **Legacy base URL**: `https://api.sequenzy.com/v1`
|
||||
- **Environment variable**: `SEQUENZY_API_KEY`
|
||||
|
||||
## MCP
|
||||
|
||||
### Quick setup
|
||||
|
||||
```bash
|
||||
npx @sequenzy/setup
|
||||
```
|
||||
|
||||
The setup wizard logs in, creates a personal API key, and configures supported MCP clients when possible.
|
||||
|
||||
### Manual MCP server config
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"sequenzy": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@sequenzy/mcp"],
|
||||
"env": {
|
||||
"SEQUENZY_API_KEY": "seq_user_your_key_here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
# Using npx
|
||||
npx sequenzy --help
|
||||
|
||||
# Or install globally
|
||||
npm install -g @sequenzy/cli
|
||||
```
|
||||
|
||||
### Login
|
||||
|
||||
```bash
|
||||
sequenzy login
|
||||
sequenzy whoami
|
||||
```
|
||||
|
||||
### Common commands
|
||||
|
||||
```bash
|
||||
# Subscribers
|
||||
sequenzy subscribers list
|
||||
sequenzy subscribers list --tag vip
|
||||
sequenzy subscribers add user@example.com --tag premium --attr plan=pro
|
||||
sequenzy subscribers get user@example.com
|
||||
sequenzy subscribers remove user@example.com
|
||||
|
||||
# Transactional email
|
||||
sequenzy send user@example.com --template welcome --var name=John
|
||||
sequenzy send user@example.com --subject "Hello" --html "<h1>Hi!</h1>"
|
||||
|
||||
# Analytics
|
||||
sequenzy stats
|
||||
sequenzy stats --period 30d
|
||||
sequenzy stats --campaign camp_abc123
|
||||
sequenzy stats --sequence seq_xyz789
|
||||
```
|
||||
|
||||
## Common Agent Operations
|
||||
|
||||
### Get account
|
||||
|
||||
```bash
|
||||
GET https://api.sequenzy.com/api/v1/account
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### List subscribers
|
||||
|
||||
```bash
|
||||
GET https://api.sequenzy.com/api/v1/subscribers?page=1&limit=20&status=active&query=john&tags=customer,vip
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### Create or update subscriber
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/subscribers
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"firstName": "John",
|
||||
"lastName": "Doe",
|
||||
"tags": ["customer", "newsletter"],
|
||||
"customAttributes": {
|
||||
"plan": "pro"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add tag to subscriber
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/subscribers/tags
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"tag": "vip"
|
||||
}
|
||||
```
|
||||
|
||||
### Trigger event for subscriber
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/subscribers/events
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"event": "trial_started",
|
||||
"properties": {
|
||||
"plan": "pro"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List campaigns
|
||||
|
||||
```bash
|
||||
GET https://api.sequenzy.com/api/v1/campaigns
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### Create draft campaign
|
||||
|
||||
Create a draft campaign and linked email. A sender profile must already be configured.
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/campaigns
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "April Launch",
|
||||
"subject": "A quick update",
|
||||
"labels": ["launch"],
|
||||
"html": "<p>Hello there!</p>"
|
||||
}
|
||||
```
|
||||
|
||||
### Send campaign test
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/campaigns/{campaignId}/test
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"to": "reviewer@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### Schedule campaign
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/campaigns/{campaignId}/schedule
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"scheduledAt": "2026-05-20T15:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List sequences
|
||||
|
||||
```bash
|
||||
GET https://api.sequenzy.com/api/v1/sequences
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### Enable or disable sequence
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/sequences/{sequenceId}/enable
|
||||
POST https://api.sequenzy.com/api/v1/sequences/{sequenceId}/disable
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### Send transactional email
|
||||
|
||||
Send via a saved template slug or by passing direct subject/body content.
|
||||
|
||||
```bash
|
||||
POST https://api.sequenzy.com/api/v1/transactional/send
|
||||
|
||||
Authorization: Bearer ***
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"to": "user@example.com",
|
||||
"slug": "welcome",
|
||||
"variables": {
|
||||
"name": "John"
|
||||
},
|
||||
"subscriberExternalId": "user_123"
|
||||
}
|
||||
```
|
||||
|
||||
### Get metrics
|
||||
|
||||
```bash
|
||||
GET https://api.sequenzy.com/api/v1/metrics
|
||||
GET https://api.sequenzy.com/api/v1/metrics/campaigns/{campaignId}
|
||||
GET https://api.sequenzy.com/api/v1/metrics/sequences/{sequenceId}
|
||||
GET https://api.sequenzy.com/api/v1/metrics/recipients
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### Webhooks
|
||||
|
||||
```bash
|
||||
GET https://api.sequenzy.com/api/v1/webhooks
|
||||
POST https://api.sequenzy.com/api/v1/webhooks
|
||||
PATCH https://api.sequenzy.com/api/v1/webhooks/{id}
|
||||
DELETE https://api.sequenzy.com/api/v1/webhooks/{id}
|
||||
POST https://api.sequenzy.com/api/v1/webhooks/{id}/test
|
||||
|
||||
Authorization: Bearer ***
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **Subscribers** - Contacts with email, status, tags, custom attributes, and optional external IDs
|
||||
- **Tags** - Lightweight labels used for targeting and segmentation
|
||||
- **Segments** - Dynamic subscriber groups based on attributes or engagement
|
||||
- **Campaigns** - Draftable and schedulable one-time marketing sends
|
||||
- **Sequences** - Automated lifecycle flows that can be enabled, disabled, and measured
|
||||
- **Templates** - Reusable email content for transactional and marketing workflows
|
||||
- **Transactional emails** - Single-recipient or small batch sends triggered by product events
|
||||
- **Engagement metrics** - Sent, delivered, bounced, opened, clicked, unsubscribed, and derived rates
|
||||
|
||||
## Safety Notes
|
||||
|
||||
- Inspect account, sender profile, audience, and target objects before mutating anything.
|
||||
- Prefer creating drafts and sending tests before scheduling or enabling live delivery.
|
||||
- Do not schedule a campaign, enable a sequence, or send a live transactional email without explicit approval.
|
||||
- Use recipient status, bounce, complaint, and unsubscribe data to avoid sending to suppressed contacts.
|
||||
- Use direct API calls for high-volume or scripted operations; use MCP or CLI for agent-driven interactive workflows.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Managing subscribers, tags, lists, and segments
|
||||
- Drafting and scheduling lifecycle campaigns
|
||||
- Building onboarding, activation, retention, or winback sequences
|
||||
- Sending product-triggered transactional emails
|
||||
- Reviewing campaign, sequence, and recipient engagement metrics
|
||||
- Connecting AI agents to email marketing operations through MCP
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- Check the latest Sequenzy API documentation for plan-specific limits.
|
||||
- Use pagination for list endpoints; subscriber lists support `page` and `limit` with a maximum limit of 100.
|
||||
|
||||
## Relevant Skills
|
||||
|
||||
- emails
|
||||
- onboarding
|
||||
- analytics
|
||||
- launch
|
||||
Reference in New Issue
Block a user