arkaos 4.26.0 → 4.27.0

package/departments/marketing/tools/integrations/truelist.md

@@ -0,0 +1,184 @@
+# Truelist
+
+Email verification and deliverability validation. Validates single emails synchronously or bulk lists asynchronously. Returns an `email_state` + `email_sub_state` plus rich metadata (domain, MX record, suggested correction, disposable/role classification).
+
+Spec source: [Truelist-Labs/truelist-openapi](https://github.com/Truelist-Labs/truelist-openapi) (OpenAPI 3.1).
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API, OpenAPI 3.1 spec |
+| MCP | ✓ | Official [truelist-mcp](https://github.com/Truelist-Labs/truelist-mcp) server (Claude, Cursor, VS Code) |
+| CLI | ✓ | Official Go [truelist-cli](https://github.com/Truelist-Labs/truelist-cli) |
+| SDK | ✓ | Official: Node/TypeScript, Python, Ruby, PHP, Go, Java, C#/.NET. Framework integrations: Django, Laravel, Next.js, Rails, React, Svelte, Vue, WordPress |
+
+## Authentication
+
+- **Type**: Bearer token (API key)
+- **Header**: `Authorization: Bearer YOUR_API_KEY`
+- **Get key**: https://truelist.io/settings/api-keys
+- **Base URL**: `https://api.truelist.io`
+
+## Common Agent Operations
+
+### Verify a single email (synchronous)
+
+```bash
+POST https://api.truelist.io/api/v1/verify_inline?email=user@example.com
+Authorization: Bearer YOUR_API_KEY
+```
+
+No request body — the email is a query parameter. Returns a single-element `emails` array with verification fields:
+
+```json
+{
+  "emails": [
+    {
+      "address": "user@example.com",
+      "domain": "example.com",
+      "canonical": "user@example.com",
+      "mx_record": null,
+      "first_name": null,
+      "last_name": null,
+      "email_state": "ok",
+      "email_sub_state": "email_ok",
+      "verified_at": "2026-02-21T10:39:12.570Z",
+      "did_you_mean": null
+    }
+  ]
+}
+```
+
+### Bulk verification (asynchronous)
+
+```bash
+POST https://api.truelist.io/api/v1/verify
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+
+{
+  "emails": [
+    "user1@example.com",
+    "user2@example.com"
+  ]
+}
+```
+
+Processes the list in the background. The response acknowledges submission; results are available via the dashboard, the Truelist UI's CSV download, or via integrations (Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, etc.).
+
+For large lists, the dashboard's CSV upload + download flow is typically the lowest-friction path.
+
+### Get account information
+
+```bash
+GET https://api.truelist.io/me
+Authorization: Bearer YOUR_API_KEY
+```
+
+Returns email, name, UUID, time zone, admin role, API keys, and account plan info.
+
+## Response Fields (per email)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `address` | string | The email address validated |
+| `domain` | string | The domain part of the address |
+| `canonical` | string | Canonical form of the address |
+| `mx_record` | string \| null | MX record for the domain |
+| `first_name` | string \| null | First name if detected |
+| `last_name` | string \| null | Last name if detected |
+| `email_state` | enum | Overall validation verdict (see below) |
+| `email_sub_state` | enum | More specific reason (see below) |
+| `verified_at` | datetime (ISO 8601) | When verification ran |
+| `did_you_mean` | string \| null | Suggested correction for typos |
+
+## `email_state` values
+
+| State | Meaning | What to do |
+|-------|---------|-----------|
+| `ok` | The email address is deliverable. | Include in outreach |
+| `email_invalid` | The email address is not deliverable. | Exclude — would bounce |
+| `risky` | May be deliverable but carries risk (role address, disposable, etc.) | Include cautiously, lower priority |
+| `unknown` | Deliverability could not be determined (timeout/connection). | Skip or re-verify with Thorough strategy |
+| `accept_all` | The mail server accepts all addresses (catch-all domain) | Include cautiously — can't confirm specific mailbox |
+
+## `email_sub_state` values
+
+| Sub-state | Meaning |
+|-----------|---------|
+| `email_ok` | Passed all checks |
+| `is_disposable` | Disposable / temporary provider (e.g., 10minutemail) |
+| `is_role` | Role-based address (info@, sales@, admin@) |
+| `unknown_error` | Sub-state could not be determined |
+| `failed_smtp_check` | SMTP check failed |
+
+Pair the two: `email_state: ok` + `email_sub_state: is_role` means "deliverable but a role inbox," whereas `email_state: email_invalid` + `email_sub_state: failed_smtp_check` means "doesn't exist."
+
+## Rate Limits
+
+| Endpoint | Limit |
+|----------|-------|
+| `/api/v1/verify_inline` | 10 requests/second |
+| `/api/v1/verify` | 10 requests/second |
+| `/me` | 10 requests/second |
+
+A 429 is returned on rate-limit exceed. Note: the per-email validation rate is separate and depends on your plan.
+
+## Error Responses
+
+| Code | Meaning |
+|------|---------|
+| 401 | Unauthorized — API key missing, invalid, or expired |
+| 429 | Rate limit exceeded |
+| 500 | Server error |
+
+All error bodies follow `{"error": "<human-readable message>"}`.
+
+## When to Use
+
+- **Before adding contacts to any cold outreach list** — non-negotiable safety step. Apollo/ZoomInfo/Hunter data accuracy is typically 60–80%; Truelist catches the rest.
+- **Real-time form validation** — block disposable / typo'd emails at signup. Use the inline endpoint (or the [form validation widget](https://truelist.io/docs/form-validation-widget)).
+- **Periodic list hygiene** — re-verify your active list quarterly to remove bounces before they hurt sender reputation.
+- **Pre-import validation** on email platform imports (Mailchimp, Klaviyo, HubSpot, etc.) — direct integrations exist for most.
+- **AI agent workflows** via the official MCP server for Claude, Cursor, and VS Code.
+
+## Why This Step is Non-Negotiable
+
+Cold email reputation is built over months and destroyed in days. ISPs (Gmail, Outlook, etc.) track sender reputation through:
+
+- **Bounce rate** — bounces over 2% trigger throttling
+- **Spam complaints** — spam traps in unvalidated lists generate complaints
+- **Engagement** — sending to dead mailboxes hurts engagement metrics
+
+A single unvalidated send to a bought or scraped list can damage a domain's sending reputation for months.
+
+## Workflow Integration
+
+Typical prospecting flow:
+
+1. Build initial prospect list (Apollo, Clay, ZoomInfo, Hunter, GitHub stargazers, etc.)
+2. **For agent-driven workflows**: use the Truelist MCP server to validate inline as the agent builds the list
+3. **For programmatic workflows**: POST emails to `/api/v1/verify` for async bulk OR `/api/v1/verify_inline` for sync single
+4. **For one-offs**: CSV upload via dashboard, download annotated CSV
+5. Filter: keep `email_state: ok`, include `risky`/`accept_all` cautiously with a strategy, exclude `email_invalid`, re-verify `unknown`
+6. Hand cleaned list to outreach platform (Instantly, Lemlist, Outreach, etc.) — see [outreach.md](outreach.md), [instantly.md](instantly.md), [lemlist.md](lemlist.md)
+
+## Native Integrations (no API code required)
+
+For non-developer workflows, Truelist has direct integrations:
+
+- **Email platforms**: Mailchimp, Klaviyo, HubSpot, ActiveCampaign, Brevo, Constant Contact, ConvertKit, Drip
+- **Automation**: Zapier, Make.com, n8n
+- **CRM / sales**: Salesforce, Go High Level, Clay.com
+- **Ecom**: BigCommerce
+- **AI / agents**: MCP server (Claude, Cursor, VS Code)
+
+See https://truelist.io/integrations for the current list.
+
+## Relevant Skills
+
+- prospecting (primary use case — validate before adding to outreach lists)
+- cold-email (downstream outreach against the validated list)
+- emails (transactional senders + subscriber list hygiene)
+- popups (real-time form validation on opt-in capture)

package/departments/marketing/tools/integrations/trustpilot.md

@@ -0,0 +1,191 @@
+# Trustpilot
+
+Business review management platform for collecting, managing, and showcasing customer reviews.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Business Units, Reviews, Invitations, Tags |
+| MCP | - | Not available |
+| CLI | ✓ | [trustpilot.js](../clis/trustpilot.js) |
+| SDK | ✓ | Node.js (official), community wrappers |
+
+## Authentication
+
+- **Type**: API Key (public endpoints) + OAuth 2.0 (private endpoints)
+- **Public Header**: `apikey: {YOUR_API_KEY}`
+- **Private Header**: `Authorization: Bearer {access_token}`
+- **OAuth Grant**: Client Credentials (`Basic base64(API_KEY:API_SECRET)`)
+- **Token Lifetime**: Access tokens expire after 100 hours, refresh tokens after 30 days
+- **Get credentials**: https://businessapp.b2b.trustpilot.com/ > Integrations > API
+
+## Common Agent Operations
+
+### Search for a business unit
+
+```bash
+GET https://api.trustpilot.com/v1/business-units/search?query=example.com&limit=10
+
+Headers:
+  apikey: {API_KEY}
+```
+
+### Get business unit details
+
+```bash
+GET https://api.trustpilot.com/v1/business-units/{businessUnitId}
+
+Headers:
+  apikey: {API_KEY}
+```
+
+### Get business profile info
+
+```bash
+GET https://api.trustpilot.com/v1/business-units/{businessUnitId}/profileinfo
+
+Headers:
+  apikey: {API_KEY}
+```
+
+### List public reviews
+
+```bash
+GET https://api.trustpilot.com/v1/business-units/{businessUnitId}/reviews?perPage=20&orderBy=createdat.desc
+
+Headers:
+  apikey: {API_KEY}
+```
+
+### List private reviews (with customer data)
+
+```bash
+GET https://api.trustpilot.com/v1/private/business-units/{businessUnitId}/reviews?perPage=20
+
+Headers:
+  Authorization: Bearer {access_token}
+```
+
+### Reply to a review
+
+```bash
+POST https://api.trustpilot.com/v1/private/reviews/{reviewId}/reply
+
+Headers:
+  Authorization: Bearer {access_token}
+
+{
+  "message": "Thank you for your feedback!"
+}
+```
+
+### Send email invitation
+
+```bash
+POST https://api.trustpilot.com/v1/private/business-units/{businessUnitId}/email-invitations
+
+Headers:
+  Authorization: Bearer {access_token}
+
+{
+  "consumerEmail": "customer@example.com",
+  "consumerName": "Jane Doe",
+  "referenceNumber": "order-123",
+  "redirectUri": "https://example.com/thanks"
+}
+```
+
+### Generate review invitation link
+
+```bash
+POST https://api.trustpilot.com/v1/private/business-units/{businessUnitId}/invitation-links
+
+Headers:
+  Authorization: Bearer {access_token}
+
+{
+  "email": "customer@example.com",
+  "name": "Jane Doe",
+  "referenceId": "order-123",
+  "redirectUri": "https://example.com/thanks"
+}
+```
+
+### List invitation templates
+
+```bash
+GET https://api.trustpilot.com/v1/private/business-units/{businessUnitId}/templates
+
+Headers:
+  Authorization: Bearer {access_token}
+```
+
+### Add tags to a review
+
+```bash
+PUT https://api.trustpilot.com/v1/private/reviews/{reviewId}/tags
+
+Headers:
+  Authorization: Bearer {access_token}
+
+{
+  "tags": [{ "group": "sentiment", "value": "positive" }]
+}
+```
+
+## Key Metrics
+
+### Business Unit Metrics
+- `numberOfReviews` - Total review count
+- `trustScore` - Overall trust score (1-5)
+- `stars` - Star rating displayed
+- `status` - Claim status (claimed, unclaimed)
+
+### Review Metrics
+- `stars` - Individual review star rating (1-5)
+- `language` - Review language code
+- `createdAt` - Review creation timestamp
+- `isVerified` - Whether the review is verified
+- `status` - Review status (active, reported, flagged)
+
+## Parameters
+
+### Review Filters
+- `stars` - Filter by star rating (1-5)
+- `language` - Filter by language code (e.g., `en`)
+- `orderBy` - Sort order (`createdat.desc`, `createdat.asc`, `stars.desc`, `stars.asc`)
+- `perPage` - Results per page (max 100)
+
+### Invitation Parameters
+- `consumerEmail` - Recipient email (required)
+- `consumerName` - Recipient name (required)
+- `referenceNumber` - Order or transaction reference
+- `templateId` - Email template ID
+- `redirectUri` - URL to redirect after review submission
+- `senderEmail` - Custom sender email
+- `replyTo` - Custom reply-to address
+
+## When to Use
+
+- Collecting and managing customer reviews at scale
+- Automating post-purchase review invitation flows
+- Monitoring brand reputation and review sentiment
+- Responding to customer feedback programmatically
+- Showcasing TrustScore and reviews on marketing pages
+- Tagging and categorizing reviews for analysis
+
+## Rate Limits
+
+- Recommended: no more than 833 calls per 5 minutes (10K/hour)
+- Throttled at more than 1 request per second
+- Rate limit headers returned in responses
+- Use webhooks instead of polling where possible
+
+## Relevant Skills
+
+- reputation-management
+- customer-feedback
+- review-generation
+- social-proof
+- post-purchase-flow

package/departments/marketing/tools/integrations/twilio.md

@@ -0,0 +1,152 @@
+# Twilio
+
+Programmable communications platform: SMS, MMS, WhatsApp, voice, email (via SendGrid). The default low-level API for custom SMS builds, transactional messaging, and B2B SaaS embedding SMS into products.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API, well-documented, mature |
+| MCP | - | Not available natively (community wrappers exist) |
+| CLI | ✓ | Official `twilio` CLI |
+| SDK | ✓ | Node, Python, Ruby, PHP, Java, Go, C#, .NET |
+
+## Authentication
+
+- **Type**: Basic auth with Account SID + Auth Token (or API Key SID + Secret)
+- **Header**: `Authorization: Basic base64(AccountSID:AuthToken)`
+- **Get credentials**: https://console.twilio.com → Account Info
+- **Recommendation**: Use API Keys (revocable, scoped) for production rather than the master Auth Token
+
+## Common Agent Operations
+
+### Send SMS
+
+```bash
+POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
+
+To=+15551234567
+From=+15559876543
+Body=Hello from Twilio
+```
+
+### Send MMS
+
+```bash
+POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
+
+To=+15551234567
+From=+15559876543
+Body=Check this out
+MediaUrl=https://example.com/image.jpg
+```
+
+### List messages
+
+```bash
+GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json?PageSize=50
+```
+
+### Get message status
+
+```bash
+GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json
+```
+
+Status values: `queued`, `sending`, `sent`, `delivered`, `undelivered`, `failed`.
+
+### List phone numbers
+
+```bash
+GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json
+```
+
+### Buy a phone number
+
+```bash
+POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json
+
+PhoneNumber=+15559876543
+```
+
+### Configure webhook for inbound messages
+
+```bash
+POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json
+
+SmsUrl=https://your-app.com/sms-webhook
+SmsMethod=POST
+```
+
+Inbound SMS POSTs to the webhook with: `From`, `To`, `Body`, `MessageSid`, `NumMedia`, etc.
+
+### A2P 10DLC registration (US)
+
+```bash
+# Create brand
+POST https://messaging.twilio.com/v1/a2p/BrandRegistrations
+
+CustomerProfileBundleSid=...
+A2PProfileBundleSid=...
+
+# Create campaign
+POST https://messaging.twilio.com/v1/Services/{ServiceSid}/Compliance/Usa2p
+
+BrandRegistrationSid=...
+Description=...
+MessageSamples[]=Sample text 1
+MessageFlow=Opt-in flow description
+UseCase=MARKETING
+```
+
+Most workflows are clearer in the Console UI. Programmatic registration is for high-scale platforms managing many brands.
+
+## API Pattern
+
+REST + form-encoded request bodies (not JSON for most endpoints). Resources nested under Account: `/Accounts/{AccountSid}/...`. Pagination via `Page`, `PageSize`, `NextPageUri`.
+
+## Key Concepts
+
+- **Messaging Service**: virtual sender container; load-balances across multiple numbers, handles A2P registration grouping
+- **Sticky Sender**: same recipient always receives from the same number within a service
+- **Geo-Match**: route to a number matching the recipient's country/region
+- **Status Callback**: webhook fired on every delivery state change
+- **Carrier Lookup**: pre-send check for line type (mobile, landline, VoIP) — costs ~$0.005
+
+## Pricing
+
+- US 10DLC SMS: $0.0079/msg
+- US toll-free SMS: $0.0079/msg
+- US short code SMS: $0.0079/msg + $1,000/mo lease
+- MMS: ~$0.02
+- Carrier surcharges (~$0.005 US 10DLC)
+- A2P 10DLC: ~$15 brand + $10/mo per campaign
+- Phone number rental: $1.15/mo (10DLC) to $2/mo (toll-free)
+
+## Rate Limits
+
+- Default: 1 msg/sec on long codes (10DLC trust score raises this to 4–100+)
+- Short code: 100+ msg/sec
+- Messaging Services throttle automatically
+- Carrier filtering applies above contracted throughput
+
+## When to Use
+
+- Building custom SMS flows into a product (B2B SaaS, mobile apps)
+- Transactional and auth SMS (OTPs, alerts, notifications)
+- Multi-channel orchestration (SMS + voice + WhatsApp)
+- High-volume programmable messaging
+- When you need full control and minimal abstraction
+- Backing store for Customer.io / Segment / other orchestration layers
+
+## When NOT to Use
+
+- DTC ecom marketing flows — use Klaviyo, Postscript, or Attentive (better tooling for cart recovery, segments, A/B tests)
+- If you don't want to handle compliance plumbing — Twilio gives you primitives, not policy
+- Marketing UI for non-technical users — there isn't one
+
+## Relevant Skills
+
+- sms
+- emails (transactional sister product via SendGrid)
+- onboarding (post-signup SMS milestones)