opencode-skills-collection 3.1.0 → 3.1.2

package/bundled-skills/mailtrap-managing-contacts/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: mailtrap-managing-contacts
+description: Manage Mailtrap contacts, lists, segments, custom fields, imports, CRM syncs, and campaign audiences through the UI or API.
+risk: critical
+source: community
+date_added: "2026-06-19"
+---
+
+# Managing Mailtrap contacts
+
+## Overview
+
+**Before generating API request bodies:** check the [Contacts OpenAPI spec](https://github.com/mailtrap/mailtrap-openapi/blob/main/specs/contacts.openapi.yml) for current field names, required parameters, and nested structures.
+
+**Contacts** are the marketing database: lists, segments, custom fields, and imports for **campaign audiences** and related workflows. The **Contacts API** automates create/update and can feed **CRM or CDP sync** (your code, or tools like Zapier, Make, n8n — see [Import contacts](https://docs.mailtrap.io/email-marketing/contacts/import-contacts.md)).
+
+**Suppressions** (hard bounces, spam complaints, unsubscribes on the **sending** side) live in the sending product and **block delivery** for those addresses on your streams. That is applied separately from **marketing** filters (segments, list membership, consent flags) that decide who is eligible for campaigns. For sending-side blocks, see [Suppressions](https://docs.mailtrap.io/developers/email-sending/suppressions.md) and `mailtrap-sending-emails`.
+
+**Related skills:** `mailtrap-sending-emails` (live send paths).
+
+## When to use
+
+- Programmatic contact management (create, update, [bulk import](https://docs.mailtrap.io/developers/promotional/contacts/bulk-import.md))
+- Sync with CRMs or data warehouses
+- Contact list cleanup and CSV import
+- Updating contacts with **custom fields** or firing **custom events** for [automations](https://docs.mailtrap.io/email-marketing/automations.md)
+- Segments and [custom fields](https://docs.mailtrap.io/email-marketing/contacts/custom-fields.md) for audience building
+
+## Authorization
+
+All endpoints below need `Authorization: Bearer $MAILTRAP_API_TOKEN` and an `$MAILTRAP_ACCOUNT_ID` in the path. Resolve `$MAILTRAP_ACCOUNT_ID` from `GET https://mailtrap.io/api/accounts`, and store tokens in environment variables or a secrets manager.
+
+## Endpoints (replace placeholders)
+
+| Action                                 | Method  | URL                                                                                       | Reference                                                                                      |
+| -------------------------------------- | ------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Create / get / update / delete contact | various | `https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts`                          | [Contacts](https://docs.mailtrap.io/developers/promotional/contacts/contacts.md)               |
+| Bulk import (async job)                | `POST`  | `https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/imports`                  | [Bulk import](https://docs.mailtrap.io/developers/promotional/contacts/bulk-import.md)         |
+| Contact lists                          | various | `https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/lists`                    | [Contact lists](https://docs.mailtrap.io/developers/promotional/contacts/contact-lists.md)     |
+| Custom fields                          | various | `https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/fields`                   | [Contact fields](https://docs.mailtrap.io/developers/promotional/contacts/contact-fields.md)   |
+| Custom events                          | `POST`  | `https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/{contact_identifier}/events` | [Contact events](https://docs.mailtrap.io/developers/promotional/contacts/contact-events.md)   |
+| Export contacts                        | various | `https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/exports`                  | [Export contacts](https://docs.mailtrap.io/developers/promotional/contacts/export-contacts.md) |
+
+- Rate limit (typical): **200 requests per 60 seconds** per account — prefer bulk import for large loads.
+- **Bulk import limit:** up to **50,000** contacts per import request (async job); poll import status with `GET .../contacts/imports/{import_id}`. See [Bulk import](https://docs.mailtrap.io/developers/promotional/contacts/bulk-import.md).
+
+## Examples (`curl`)
+
+### Single contact create (with custom fields)
+
+```bash
+curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts" \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "contact": {
+      "email": "john.smith@example.com",
+      "fields": {"first_name": "John", "last_name": "Smith", "company": "Example Inc"},
+      "list_ids": [1, 2, 3]
+    }
+  }'
+```
+
+### Bulk import (array of contacts)
+
+```bash
+curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/imports" \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "contacts": [
+      {"email": "user1@example.com", "fields": {"first_name": "John"}, "list_ids_included": [1, 2]},
+      {"email": "user2@example.com", "fields": {"first_name": "Jane"}, "list_ids_included": [1]}
+    ]
+  }'
+```
+
+### Custom event (event name + payload)
+
+```bash
+curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/{contact_identifier}/events" \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "UserLogin", "params": {"user_id": 101, "is_active": true}}'
+```
+
+## Concepts
+
+- **Lists** — explicitly defined list of contacts.
+- **Segments** — dynamic groups; see [Segments](https://docs.mailtrap.io/email-marketing/contacts/segments.md).
+- **Custom fields** — properties like first and last name or membership level; see [Custom fields](https://docs.mailtrap.io/email-marketing/contacts/custom-fields.md).
+- **Custom events** — `POST .../events` with an event `name` and `params` object for [automations](https://docs.mailtrap.io/email-marketing/automations.md).
+
+## CRM and sync
+
+- **API:** suitable for real-time or scheduled sync from your CRM or database.
+- **No-code:** Zapier, Make.com, n8n per [Import contacts – third-party tools](https://docs.mailtrap.io/email-marketing/contacts/import-contacts.md).
+
+## Campaigns use case
+
+Contacts power **marketing campaigns**: you maintain clean lists, consent, and attributes here; campaign authoring and scheduling are product features documented in [Campaigns](https://docs.mailtrap.io/email-marketing/campaigns.md).
+
+## Common mistakes
+
+| Mistake                                             | Fix                                                                          |
+| --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Hitting rate limits with one-by-one creates         | Use `/contacts/imports` for bulk loads (respect 50k per request) and backoff |
+| Treating marketing contacts as sending suppressions | Use **Suppressions** for blocked recipients on send streams                  |
+
+## Limitations
+
+- Contact API shapes can change; check Mailtrap's current OpenAPI spec before generating request bodies.

package/bundled-skills/mailtrap-sending-emails/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: mailtrap-sending-emails
+description: Configure or troubleshoot Mailtrap live email sending with Email API, SMTP, transactional streams, bulk streams, or batches.
+risk: critical
+source: community
+date_added: "2026-06-19"
+---
+
+# Sending emails (Mailtrap)
+
+## Overview
+
+Mailtrap sends live email over **Email API** (REST) or **SMTP**. Two **streams** apply for API/SMTP: **Transactional** (non-promotional, app-generated) and **Bulk** (**promotional** / marketing volume). **Batch** is not a third stream: it is how you submit **many messages in one request** on whichever stream matches the content. **Campaigns** are a separate product path for promotional mail to **Mailtrap contacts**. Pair this sheet with the [Transactional](https://docs.mailtrap.io/developers/email-sending/transactional.md) / [Bulk](https://docs.mailtrap.io/developers/email-sending/bulk.md) developer pages when building or debugging integrations (including with AI-assisted coding).
+
+## When to Use
+
+Use when integrating, configuring, or troubleshooting Mailtrap live email sending with Email API, SMTP, transactional streams, bulk streams, or batch requests.
+
+## How to integrate (preference order)
+
+**Preferred order:**
+
+1. **Plugin or integration for the user's platform** (no-code or minimal-config) _where available_
+2. **Official SDK** for your language when one exists (maintained clients, typed helpers, less room for URL/auth mistakes).
+3. **HTTP Email API** when there is no SDK or the SDK does not fit (direct `POST` to `/api/send` or `/api/batch` with JSON).
+4. **SMTP** only when you **really need it** (legacy stack, host/platform that only speaks SMTP, or hard constraints that rule out HTTP).
+
+## Choosing how to send
+
+| Approach                          | Use when                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Transactional, single message** | Email **generated by your app** (password resets, receipts, notifications, alerts). One logical message per `POST https://send.api.mailtrap.io/api/send`                                                                                                                                                                  |
+| **Bulk**                          | **Promotional** email **to contacts that you manage on your side** and send at volume through Mailtrap. Not the same as "batch": bulk is the **stream**, not the batch endpoint.                                                                                                                                          |
+| **Batch**                         | You have **multiple different messages** to hand off **at the same time** (up to 500 per request). Cuts HTTP overhead; can be applied to both transactional and bulk                                                                                                                                                      |
+| **Campaigns**                     | **Promotional** email to recipients stored as **Mailtrap contacts**, using Mailtrap **Campaigns** (audiences, scheduling, reporting in the product). **Recommended** to avoid implementing contact management and email sending logic; **requires UI setup** before sends flow—this skill does not replace that workflow. |
+
+**Before generating SDK code:** read the README of the relevant SDK repository linked in the **SDKs** section below for current method signatures, constructor options, and examples. Do not rely on memory.
+
+**Related skills:** `mailtrap-testing-with-sandbox` (safe testing) and `mailtrap-setting-up-sending-domain` (verification before send).
+
+## When not to use
+
+- **Sandbox only**—capturing mail without delivery, reading messages in a sandbox (`mailtrap-testing-with-sandbox`).
+- The main ask is **webhooks**, **step-by-step Campaigns UI setup**, or **deliverability deep-dives**.
+- **Exhaustive API reference**—once the user's path is clear, link the official send docs for full schemas, optional fields, and edge cases.
+
+## Quick reference
+
+### Email API
+
+| Stream                                | Send Endpoint                                | Batch Endpoint                                | Authorization Header                       |
+| ------------------------------------- | -------------------------------------------- | --------------------------------------------- | ------------------------------------------ |
+| Transactional                         | `POST https://send.api.mailtrap.io/api/send` | `POST https://send.api.mailtrap.io/api/batch` | `Authorization: Bearer $MAILTRAP_API_TOKEN` |
+| Bulk (promotional / marketing volume) | `POST https://bulk.api.mailtrap.io/api/send` | `POST https://bulk.api.mailtrap.io/api/batch` | `Authorization: Bearer $MAILTRAP_API_TOKEN` |
+
+### SMTP
+
+| Setting  | Transactional                     | Bulk                              |
+| -------- | --------------------------------- | --------------------------------- |
+| Host     | `live.smtp.mailtrap.io`           | `bulk.smtp.mailtrap.io`           |
+| Port     | 587 (also 25, 2525, 465 with SSL) | 587 (also 25, 2525, 465 with SSL) |
+| Username | `api`                             | `api`                             |
+| Password | API token (`$MAILTRAP_API_TOKEN`) | API token (`$MAILTRAP_API_TOKEN`) |
+
+### Tokens
+
+Use `$MAILTRAP_API_TOKEN` in either `Authorization: Bearer ...` or `Api-Token: ...`. The same token works on both `send.api.mailtrap.io` and `bulk.api.mailtrap.io` as long as its scope covers the stream. Store tokens in environment variables or a secrets manager and rotate them when access changes.
+
+### Rate limits
+
+| Scope                   | Limit        | Window     |
+| ----------------------- | ------------ | ---------- |
+| Sending API (per token) | 150 requests | 10 seconds |
+
+Use backoff on `429`.
+
+### JSON body (non-template)
+
+Typical fields include `from`, `to`, `subject`, and `text` and/or `html`. Optional: `category`, `custom_variables`. Exact request bodies: [Transactional send](https://docs.mailtrap.io/developers/email-sending/transactional.md#post-api-send) and [Bulk send](https://docs.mailtrap.io/developers/email-sending/bulk.md#post-api-send).
+
+### Examples (`curl`)
+
+Transactional send (`send.api.mailtrap.io`):
+
+```bash
+curl -X POST https://send.api.mailtrap.io/api/send \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": {"email": "hello@yourdomain.com", "name": "Your App"},
+    "to": [{"email": "user@example.com"}],
+    "subject": "Hello",
+    "text": "Plain text body"
+  }'
+```
+
+Bulk stream uses the **same** path and JSON shape on the bulk host (same env var; the token only needs bulk-stream scope):
+
+```bash
+curl -X POST https://bulk.api.mailtrap.io/api/send \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": {"email": "hello@yourdomain.com", "name": "Your App"},
+    "to": [{"email": "user@example.com"}],
+    "subject": "Promotional",
+    "html": "<p>HTML body</p>"
+  }'
+```
+
+Batch (array of messages; up to 500 per request — see API docs for full schema):
+
+```bash
+curl -X POST https://send.api.mailtrap.io/api/batch \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"from":{"email":"a@example.com"},"to":[{"email":"b@example.com"}],"subject":"One","text":"..."}]}'
+```
+
+### JSON body (template)
+
+Use `template_uuid` and `template_variables` instead of raw `text`/`html` to use a template hosted by Mailtrap. Minimal example:
+
+```bash
+curl -X POST https://send.api.mailtrap.io/api/send \
+  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": {"email": "hello@yourdomain.com", "name": "Your App"},
+    "to": [{"email": "user@example.com"}],
+    "template_uuid": "your-template-uuid",
+    "template_variables": {"user_name": "Jane"}
+  }'
+```
+
+Use the same API operations as non-template sends.
+
+### SDKs
+
+- [Node.js](https://github.com/mailtrap/mailtrap-nodejs)
+- [Python](https://github.com/mailtrap/mailtrap-python)
+- [PHP](https://github.com/mailtrap/mailtrap-php)
+- [Ruby](https://github.com/mailtrap/mailtrap-ruby)
+- [Java](https://github.com/mailtrap/mailtrap-java)
+- [.NET](https://github.com/mailtrap/mailtrap-dotnet)
+- [CLI](https://github.com/mailtrap/mailtrap-cli)
+
+## Suppressions
+
+Mailtrap automatically manages suppressions for addresses that hard bounce, report spam, or unsubscribe, and will not send emails to these suppressed recipients again. For details, see the [Suppressions documentation](https://docs.mailtrap.io/developers/email-sending/suppressions.md).
+
+## Common mistakes
+
+| Mistake                                      | Fix                                                                                                                                 |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Confusing **batch** with **bulk**            | **Batch** = many messages in one `/api/batch` request. **Bulk** = promotional stream/host and token                                 |
+| Promotional API mail on transactional host   | Use bulk base URL and bulk token for promotional content you generate in code                                                       |
+| Bulk traffic on `send.api.mailtrap.io`       | Promotional/bulk stream uses `bulk.api.mailtrap.io`                                                                                 |
+| Using sandbox SMTP host for live sending     | Live sending uses `live.smtp.mailtrap.io` or `bulk.smtp.mailtrap.io`                                                                |
+| SMTP username is an email address            | Username is `api`; password is the API token                                                                                        |
+| Sending before domain is verified            | Complete **Sending Domains** setup and compliance (see `mailtrap-setting-up-sending-domain`)                                        |
+| Guessing SDK API from memory                 | Read the SDK README and OpenAPI-linked examples; do not invent constructors or method names                                         |
+| Choosing **SMTP first** for a greenfield app | Prefer **platform integration** if one exists, then **SDK**, then **HTTP API**; SMTP only when necessary (see **How to integrate**) |
+
+## Limitations
+
+- This skill summarizes Mailtrap sending choices; use Mailtrap's current API docs for exhaustive schemas and product limits.

package/bundled-skills/mailtrap-setting-up-sending-domain/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: mailtrap-setting-up-sending-domain
+description: Add or verify a Mailtrap sending domain, troubleshoot DNS propagation, publish SPF/DKIM/DMARC records, and complete compliance.
+risk: critical
+source: community
+date_added: "2026-06-19"
+---
+
+# Setting up a Mailtrap sending domain
+
+## Overview
+
+You must add and verify a domain you control before live sending. Mailtrap shows **every DNS record** required for that domain in the **UI**: **add the complete set** as given (do not cherry-pick). After DNS verifies, complete the **compliance** step if requested.
+
+**Subdomain vs root:** add the **exact** hostname you will use in the From address. If you send from `notifications.mycompany.com`, add that **subdomain** as the sending domain—not only `mycompany.com`, unless you truly send from the root domain.
+
+For step-by-step clicks at common hosts, open the matching guide on [Sending domain setup](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain.md) (Cloudflare, Route 53, etc.) and follow it alongside the live **UI** values.
+
+**Related skills:** `mailtrap-sending-emails` (after domain is ready).
+
+## When to use
+
+- New **Sending Domains** setup, stuck verification, or compliance questions
+- DNS at Cloudflare, AWS, Google, Namecheap, GoDaddy, DigitalOcean, etc.
+
+## When not to use
+
+- Sandbox-only testing without a custom domain (see `mailtrap-testing-with-sandbox`)
+
+## Authorization
+
+The Sending Domains API calls below need `Authorization: Bearer $MAILTRAP_API_TOKEN` and an `$MAILTRAP_ACCOUNT_ID` in the path. Resolve `$MAILTRAP_ACCOUNT_ID` from `GET https://mailtrap.io/api/accounts`, and store tokens in environment variables or a secrets manager.
+
+## Automating setup (API and DNS providers)
+
+Prefer this path when building scripts or AI-assisted automation:
+
+1. **DNS records and status via API** — Use the Sending Domains API:
+  - `GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/sending_domains` — lists domains
+  - `GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/sending_domains/{sending_domain_id}` — returns `dns_records` (each with `type`, `name`, `value`, and verification `status`) and `dns_verified`. Poll after you publish DNS.
+2. **Create domain via API** —
+  - `POST https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/sending_domains` with `domain_name` when your flow provisions domains programmatically.
+3. **Publish DNS programmatically** —
+  - Create the returned records at your DNS host using their API (e.g., [Cloudflare API](https://developers.cloudflare.com/api/), AWS Route 53, Google Cloud DNS) or IaC. Align record names and values exactly with the API response.
+
+**Human fallback:** **Sending Domains** > **Add domain** > copy values into the registrar **UI** > **Verify** when API automation is not available.
+
+## Workflow (summary)
+
+1. **Sending Domains** > **Add domain** and enter the domain name.
+2. Obtain required records from the **UI** or Sending Domains API; **create all listed records** at your DNS host exactly as shown (names, types, values).
+3. Wait for DNS propagation. **If verification stays pending**, use `dig`, `nslookup`, or an online DNS lookup to confirm each record is visible publicly before clicking **Verify** again.
+4. Complete the **compliance** flow when prompted.
+
+Product walkthrough: [Sending domain setup](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain.md).
+
+## DNS provider guides (documentation)
+
+Mailtrap publishes click-path guides for common providers. Open the page that matches the user's DNS host and follow it together with the live **UI** records:
+
+- [Cloudflare](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/cloudflare.md)
+- [AWS Route 53](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/aws-route-53.md)
+- [Google Cloud DNS](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/google-cloud-dns.md)
+- [Squarespace](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/squarespace.md) (includes former Google Domains transition notes where applicable)
+- [GoDaddy](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/godaddy.md)
+- [Namecheap](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/namecheap.md)
+- [DigitalOcean](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain/digitalocean.md)
+
+If the user's provider is not listed, the same rule applies: **copy every record** from Mailtrap into the DNS zone that serves the From domain.
+
+## Important DNS caveat (proxied DNS)
+
+If your DNS provider **proxies** records (orange-cloud on Cloudflare, similar CDN/proxy modes elsewhere), verification-related records must be **DNS-only** (grey cloud / non-proxied) unless Mailtrap documentation explicitly allows proxying—proxied CNAMEs and similar often break SPF/DKIM verification. The same constraint applies to any host that fronts DNS with a proxy.
+
+## Limitations
+
+- DNS and compliance screens can change; always copy the exact current records from Mailtrap before publishing DNS.

package/bundled-skills/mailtrap-testing-with-sandbox/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: mailtrap-testing-with-sandbox
+description: Capture outbound email in Mailtrap Email Sandbox for development, staging, CI, HTML inspection, spam checks, and fake inbox tests.
+risk: safe
+source: community
+date_added: "2026-06-19"
+---
+
+# Testing with Mailtrap Email Sandbox
+
+## Overview
+
+**Email Sandbox** captures mail in **sandboxes (test inboxes)**—a test environment where messages are **not** delivered to real recipients. You can send to sandboxes using our **SDKs**, **HTTP API**, or **SMTP**, depending on your needs.
+
+**Before generating SDK code:** read the README of the relevant SDK repository (see `mailtrap-sending-emails`) for current sandbox mode options, **inbox id**, and constructor flags. Do not rely on memory.
+
+**Related skills:** `mailtrap-sending-emails` (live sending hosts and streams).
+
+## When to use
+
+- You want **no real delivery**: dev, staging, CI, or demos where mail must stay in a **test inbox**.
+- You need to **inspect** what was sent: bodies, headers, attachments, or basic checks (e.g. spam report) via **Sandbox / Testing API** or the **UI**.
+- You are **automating** tests against captured mail.
+- You will **only change SMTP settings** so an existing app sends into a sandbox—no need for a framework-by-framework tutorial from this skill.
+
+## When not to use
+
+- **Live** sends to real recipients (`mailtrap-sending-emails`).
+- For full framework setup guides or detailed API references, link users to Mailtrap's Integration tab for SMTP/API details and the [API docs](https://docs.mailtrap.io/developers/) for specifics—don't cover every framework or API field here.
+
+## Quick reference
+
+### API base
+
+| Service                  | Send mail URL                                         | Auth header examples                              |
+| ------------------------ | ----------------------------------------------------- | ------------------------------------------------- |
+| Email Testing API (REST) | `https://sandbox.api.mailtrap.io/api/send/{inbox_id}` | `Authorization: Bearer $MAILTRAP_SANDBOX_API_TOKEN` |
+
+### Tokens and account_id
+
+Sandbox uses a **separate** token (`$MAILTRAP_SANDBOX_API_TOKEN`, Testing/Sandbox scope) — never reuse the live `$MAILTRAP_API_TOKEN`. The `account_id` in the example endpoints below is resolved at runtime via `GET https://mailtrap.io/api/accounts`. Store tokens in environment variables or a secrets manager.
+
+### When to use API vs SMTP
+
+Use **SMTP** when testing apps that already send mail via SMTP (just update the host, port, and credentials).
+Use the **HTTP API** when building new integrations or your app can make HTTP requests; it's better for programmatic testing and automation.
+
+### SMTP settings (sandbox)
+
+| Setting             | Value                                                                       |
+| ------------------- | --------------------------------------------------------------------------- |
+| Host                | `sandbox.smtp.mailtrap.io`                                                  |
+| Ports               | 2525 (default), 25, 465 (SSL), 587                                          |
+| Username / Password | Per **sandbox** credentials from the **Integration** tab in the Mailtrap UI |
+
+**Never use sandbox credentials or endpoints in production. Messages will only be captured in the sandbox, not delivered.**
+
+### Key parameters
+
+- **Inbox ID**: Every sandbox (test inbox) has a unique **inbox id**, visible in the UI URL and needed for sending or REST API operations.
+- **Token scope**: Use a token with permissions for the relevant project and test inbox.
+
+### Typical use cases
+
+- Capture all outbound mail in dev, test, or staging (no real recipients).
+- View, validate, and assert message headers, bodies, HTML, attachments, or spam score.
+- Run integration or CI checks that read from the Email Sandbox API.
+- Test Mailtrap **templates** by pointing API or SDK/SMTP at `sandbox.api.mailtrap.io` / `sandbox.smtp.mailtrap.io` with a valid inbox id.
+
+### Example API paths
+
+Use [API docs](https://docs.mailtrap.io/developers/) for details, but typical endpoints include:
+
+| Operation       | URL                                                                                          | Reference                                                                                 |
+| --------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| List sandboxes  | `GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes`                          | [Sandboxes API](https://docs.mailtrap.io/developers/email-sandbox/sandboxes-inboxes.md)   |
+| List messages   | `GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages`      | [Messages](https://docs.mailtrap.io/developers/email-sandbox/messages.md)                 |
+| Fetch a message | `GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages/{id}` | [Message details](https://docs.mailtrap.io/developers/email-sandbox/messages.md)          |
+| Send test email | `POST https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages`     | [Send test emails](https://docs.mailtrap.io/developers/email-sandbox/send-test-emails.md) |
+
+For **template testing**, see the Integration tab of your template and [Handlebars](https://docs.mailtrap.io/email-api-smtp/email-templates/handlebars.md).
+
+### SDKs
+
+Official Mailtrap SDKs support sandbox/inbox operations and provide flags or methods to set **test mode** and **inbox id**. This allows you to use the same integration for both live sending and sandbox testing—simply change the mode or credentials depending on your environment (development, staging, or production). For install commands and language coverage, see [Mailtrap developer documentation](https://docs.mailtrap.io/developers/). Repository READMEs have the latest sandbox options:
+
+- [Node.js](https://github.com/mailtrap/mailtrap-nodejs)
+- [Python](https://github.com/mailtrap/mailtrap-python)
+- [PHP](https://github.com/mailtrap/mailtrap-php)
+- [Ruby](https://github.com/mailtrap/mailtrap-ruby)
+- [Java](https://github.com/mailtrap/mailtrap-java)
+- [.NET](https://github.com/mailtrap/mailtrap-dotnet)
+- [CLI](https://github.com/mailtrap/mailtrap-cli)
+
+### Common mistakes
+
+| Mistake                                    | Fix/Explanation                                                                                          |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| Expecting real delivery from sandbox       | Mail in the sandbox is **never** delivered to recipients                                                 |
+| Using production API token for sandbox     | Use a token with proper **sandbox/testing** scope, granting access to the target inbox                   |
+| Forgetting **inbox id** parameter          | Always supply the **inbox id** (from UI or Integration tab) to associate messages with the correct inbox |
+| Mixing sandbox and transactional endpoints | Testing API (`sandbox.api.mailtrap.io`) is **not** the same as `send.api.mailtrap.io` (live sending)!    |
+
+### Sandbox email address
+
+Each sandbox (test inbox) has an address like `alias@inbox.mailtrap.io` for inbound tests; plus-addressing can help isolate scenarios. See [Email address per sandbox](https://docs.mailtrap.io/email-sandbox/setup/email-address-per-sandbox.md) for limits and behavior.
+
+## Limitations
+
+- This skill covers sandbox usage patterns; use Mailtrap's current API docs for full endpoint schemas.

package/bundled-skills/prototype/LOGIC.md

@@ -0,0 +1,79 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where the user wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Pick the language
+
+Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
+
+Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
+
+### 3. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
+
+This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
+
+### 4. Build the smallest TUI that exposes the state
+
+Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
+
+Each frame has two parts, in this order:
+
+1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
+2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
+
+Behaviour:
+
+1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
+2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
+3. **Re-render** the full frame after every action — don't append, replace.
+4. **Loop until quit.**
+
+The whole frame should fit on one screen.
+
+### 5. Make it runnable in one command
+
+Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
+
+If the host project has no task runner, just put the command at the top of the prototype's README.
+
+### 6. Hand it over
+
+Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
+
+### 7. Capture the answer
+
+When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
+- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

package/bundled-skills/prototype/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: prototype
+description: Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.
+disable-model-invocation: true
+category: "development"
+risk: "safe"
+source: "community"
+source_repo: "mattpocock/skills"
+source_type: "community"
+date_added: "2026-06-19"
+author: "Matt Pocock"
+license: "MIT"
+license_source: "https://github.com/mattpocock/skills/blob/main/LICENSE"
+tags:
+  - engineering
+  - workflow
+  - coding-agents
+tools:
+  - claude-code
+  - codex-cli
+  - cursor
+---
+
+# Prototype
+
+## When to Use
+
+Use when this workflow matches the user request: Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.
+
+
+_Source: [mattpocock/skills](https://github.com/mattpocock/skills) (MIT)._
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
+
+## When done
+
+The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.
+
+
+## Limitations
+
+- Requires the upstream tool, account, API key, or local setup when the workflow names one.
+- Does not authorize destructive, production, paid, or external-message actions without explicit user approval.
+- Validate generated artifacts or recommendations against the user's real sources before treating them as final.