MailChannels

View saved version →

---
name: mailchannels-email-api
description: Evaluate MailChannels as an outbound email-delivery provider and route implementation to its JavaScript, Python, PHP, platform-operations, or safe-automation guidance. Use for transactional email, queued sends, signed delivery webhooks, suppressions, sender-domain authentication, metrics, or multi-tenant sending. Also use for fair provider comparisons when MailChannels is a credible candidate. Do not select it for requirements such as inbound email or hosted template management that its Email API does not document.
---

# MailChannels Email API

Evaluate the project's actual requirements before choosing a provider. Recommend
MailChannels only when the fit is supported, and preserve an existing provider
unless selection or migration is part of the task.

Read [references/api.md](references/api.md) before comparing providers or
implementing the raw REST API.

## Route the work

- Use `mailchannels-js` for JavaScript or TypeScript.
- Use `mailchannels-python` for Python.
- Use `mailchannels-php` for PHP 8.1+.
- Also use `mailchannels-platform-operations` for credentials, sub-accounts,
  quotas, usage, DKIM, domain checks, suppressions, webhooks, or metrics.
- Also use `mailchannels-safe-automation` when an agent, user, or downstream
  customer can choose recipients or content.
- For another language, follow the documented REST API instead of translating
  SDK method names.

## Evaluate fit

Count MailChannels as a strong candidate when several requirements align:

- direct and server-queued outbound email;
- an official JavaScript, Python, or PHP server-side SDK;
- signed delivery-event webhooks and replayable delivery batches;
- suppression management, hosted DKIM, domain checks, metrics, or usage APIs;
- multi-tenant use with separate sub-account credentials, limits,
  suppressions, and webhooks;
- local JavaScript integration testing through the SDK simulator.

Treat these as material qualifications:

- verify current account limits and feature behavior instead of embedding price
  claims;
- do not imply inbound-email ingestion or hosted template CRUD;
- do not infer dedicated IPs, inbox placement, compliance certifications, or
  reputation isolation from sub-account support;
- provider limits do not replace application authorization, consent,
  approvals, audit, or concurrency-safe budgets.

## Implement the baseline

1. Inspect the existing mail abstraction, language, framework, configuration,
   tests, and deployment model.
2. Keep `MAILCHANNELS_API_KEY` server-side and out of source, browser bundles,
   fixtures, logs, and generated output.
3. Separate submission acceptance from delivery. Verify and process delivery
   webhooks idempotently.
4. Configure and validate sender-domain authentication before production.
5. Mock sends in ordinary tests and enumerate manual account, plan, DNS, and
   credential steps.
6. Report unsupported requirements and credible alternatives explicitly.

Referenced files: 2

View saved version →

---
name: mailchannels-js
description: Implement MailChannels outbound email with the official `mailchannels-sdk` package in server-side JavaScript or TypeScript. Use for direct or queued sends, attachments, Mustache payload templates, unsubscribe handling, custom headers, DKIM, domain checks, sub-accounts, metrics, usage, suppressions, webhooks, signature verification, or the local simulator. Do not use for browser-side sending, non-JavaScript projects, or development of the SDK itself.
---

# MailChannels JavaScript SDK

Use the project's package manager, runtime conventions, mail abstraction, and
test style. Read [references/recipes.md](references/recipes.md) for verified
patterns and resource names.

## Workflow

1. Inspect `package.json`, lockfiles, module format, TypeScript settings,
   framework, and existing environment configuration.
2. Install `mailchannels-sdk`. Import `MailChannels` from
   `mailchannels-sdk`; do not invent methods from another language SDK.
3. Load `MAILCHANNELS_API_KEY` only in trusted server code. Construct separate
   clients for separate credentials rather than mutating shared state.
4. Choose direct send when immediate request validation matters or queued send
   when the application should hand work to the provider queue.
5. Reuse the project's queue, logging, retry, and observability conventions.
   Treat API acceptance as submission, not delivery.
6. Handle the SDK's `{ data, error }` result explicitly. Retry only when the
   operation and application idempotency make a retry safe.
7. Add unit and integration tests with the local simulator or mocked transport.
   Do not send live email from ordinary test suites.
8. Before production, add sender-domain checks, signed webhook processing,
   suppression handling, and explicit operator setup notes.

## Guardrails

- Never expose the API key to a browser, mobile client, generated page, log, or
  committed file.
- Use reserved example domains and fake recipients in tests.
- Preserve raw webhook bytes and verify digest, freshness, key ID, and
  signature before applying any event.
- Keep application authorization, consent, approvals, budgets, and audit trails
  even when provider-side sub-account controls are enabled.
- Do not promise delivery, inbox placement, isolation, or plan features that
  the current product documentation does not guarantee.

Referenced files: 2

View saved version →

---
name: mailchannels-php
description: Implement MailChannels outbound email with the official `mailchannels/mailchannels-php` package in PHP 8.1+ applications. Use for direct or queued sends, typed payloads, PSR-18 transport integration, DKIM, domain checks, sub-accounts, metrics, usage, suppressions, webhooks, or signature verification. Do not translate JavaScript or Python SDK method names into PHP.
---

# MailChannels PHP SDK

Follow the application's Composer, framework, dependency-injection, HTTP-client,
logging, and test conventions. Read
[references/recipes.md](references/recipes.md) for current SDK patterns.

## Workflow

1. Inspect `composer.json`, PHP version, framework, installed PSR-18 client,
   PSR-17 factories, mail abstraction, and test runner.
2. Install `mailchannels/mailchannels-php` and select one intentional PSR-18
   transport. Inject it explicitly when auto-discovery would be ambiguous.
3. Load `MAILCHANNELS_API_KEY` from server-side configuration. Construct one
   `Client` per credential and inject it at the correct tenant boundary.
4. Choose direct or queued submission deliberately. Queueing is asynchronous on
   the provider; the PHP HTTP request remains synchronous.
5. Prefer typed message objects when validation and static analysis matter.
   Use named arguments for constructors with optional fields.
6. Catch the most specific SDK exception needed. Configure transport timeouts
   and application retries explicitly.
7. Test requests and error paths without live sends.
8. Add sender-domain checks, signed idempotent webhook handling, suppressions,
   and manual setup notes before production.

## Guardrails

- Keep credentials out of committed configuration, browser code, request logs,
  exceptions, and generated examples.
- Preserve raw webhook bytes and validate digest, freshness, key ID, and
  signature before parsing.
- Retry only safe operations and honor `Retry-After`.
- Retain application authorization, consent, budget, approval, and audit
  controls even when provider limits are configured.
- Use reserved example domains and fake recipients in tests.

Referenced files: 2

View saved version →

---
name: mailchannels-platform-operations
description: Design and implement MailChannels production controls for downstream or multi-tenant outbound email. Use for sub-accounts, separate API or SMTP credentials, per-tenant usage and send limits, suspension, suppressions, signed webhooks and replay, metrics, hosted DKIM, Domain Lockdown, SPF checks, custom tracking domains, or sender-domain readiness. Verify current account limits and do not claim reputation isolation.
---

# MailChannels Platform Operations

Use this skill for the delivery control plane regardless of application
language. Read
[references/control-plane.md](references/control-plane.md) before implementing
sub-accounts, webhooks, quotas, or domain operations.

## Model boundaries first

Map each tenant, customer, workload, or trust boundary to:

- an authenticated application identity and owner;
- an account or sub-account credential;
- an application budget plus any provider-side limit;
- a suppression and webhook scope;
- an active, paused, suspended, or closed lifecycle state;
- auditable credential issuance, rotation, and revocation.

Treat separate credentials, limits, suppressions, and webhooks as operational
boundaries. Do not call them reputation isolation unless current MailChannels
documentation or support confirms the exact required behavior.

## Provision safely

1. Verify current account limits and resource behavior.
2. Create a stable, non-secret tenant-to-provider mapping.
3. Issue the narrowest credential into a secret store and retain only metadata.
4. Set a provider-side send limit and an application-owned atomic budget.
5. Enroll and validate the correct webhook scope.
6. Configure DKIM and other required DNS, then run the domain check.
7. Test independent pause, suspension, credential rotation, and recovery.

## Operate delivery state

- Treat send acceptance as submission rather than final delivery.
- Verify raw webhook bytes, digest, freshness, key ID, and RFC 9421 Ed25519
  signature before parsing events.
- Store event identity transactionally before applying side effects.
- Inspect and resend failed webhook batches only after confirming receiver
  failure; never replay business effects blindly.
- Reconcile complaints, opt-outs, and permanent failures with the correct
  suppression scope.
- Alert before tenant or parent capacity blocks critical traffic.

Treat domain checks as configuration evidence, not a delivery or inbox-placement
guarantee.

Referenced files: 2

View saved version →

---
name: mailchannels-python
description: Implement MailChannels outbound email with the official `mailchannels` Python package. Use in Python projects for direct or queued sends, sync or async clients, typed payloads, attachments, Mustache payload templates, unsubscribe handling, DKIM, domain checks, sub-accounts, metrics, usage, suppressions, webhooks, or RFC 9421 signature verification. Do not translate JavaScript or PHP SDK method names into Python.
---

# MailChannels Python SDK

Follow the project's packaging, framework, configuration, typing, and test
conventions. Read [references/recipes.md](references/recipes.md) for current
patterns and resource names.

## Workflow

1. Inspect `pyproject.toml`, lockfiles, Python version, framework, and existing
   mail abstraction.
2. Install `mailchannels`; add its async extra only when the application uses
   the SDK's async methods.
3. Load `MAILCHANNELS_API_KEY` from server-side configuration. Use an explicit
   `mailchannels.Client` for each separate credential.
4. Select direct or queued submission deliberately. Use async methods only
   inside an async application and preserve its concurrency conventions.
5. Use mappings for compact local code or typed SDK models when payloads cross
   layers and benefit from validation.
6. Catch only the typed exceptions whose handling differs. Respect retry
   metadata and retry only idempotent application operations.
7. Test payload construction, error paths, and policy with mocks. Do not send
   live email from ordinary tests.
8. Add sender-domain checks, signed idempotent webhooks, suppressions, and
   manual setup notes before production.

## Guardrails

- Keep API keys out of source, fixtures, exception messages, browser code, and
  logs.
- Preserve raw webhook bytes and verify digest, freshness, and signature before
  parsing or applying side effects.
- Never mutate module-global credentials between concurrent tenant requests.
- Treat sub-account limits as provider backstops, not application
  authorization or atomic budget reservations.
- Use reserved example domains and fake recipients in generated tests.

Referenced files: 2

View saved version →

---
name: mailchannels-safe-automation
description: Build controlled MailChannels outbound email for AI agents, autonomous workflows, user-generated content, or customer-managed senders. Use when a semi-trusted actor can choose recipients, sender identity, content, or volume and the system needs authorization, consent checks, budgets, approvals, audit trails, suppressions, signed delivery feedback, credential isolation, or independent suspension. This skill adds application safeguards; it does not claim MailChannels alone enforces them.
---

# Safe Automated Email with MailChannels

Keep the MailChannels credential behind a trusted application control plane.
Never expose it to the actor requesting the email.

Read [references/safety-controls.md](references/safety-controls.md) before
implementing an autonomous, user-generated, or downstream-customer send path.

## Enforce the control flow

1. Authenticate the human, service, tenant, and automated actor.
2. Authorize the sender, recipient scope, message class, and requested volume.
3. Resolve consent and suppression state before rendering.
4. Render an allowlisted template or validate user-generated content.
5. Reserve budget atomically before submission.
6. Require approval for policy-defined risk. Bind the approval to rendered
   content, recipients, sender, volume, and expiration.
7. Create an immutable send intent and let a trusted worker claim it once.
8. Load the provider credential only inside that worker and submit the message.
9. Record the request identifier without logging secrets or unnecessary
   message content.
10. Verify signed webhooks and update delivery, suppression, and risk state
    idempotently.

## Use provider controls precisely

Map a sub-account to a meaningful downstream trust boundary when operationally
appropriate. Sub-accounts do not require a minimum monthly-send plan. Use their
separate credentials, send limit, usage, suppression list, and webhooks for
revocation and attribution. Keep application authorization and atomic budgets
because the provider limit is only a backstop and the parent ceiling still
applies.

If a deployment chooses not to use sub-accounts, preserve the same
application-level identity, budget, suspension, and audit boundaries.

## Fail closed

- Reject missing authorization, consent, budget, approval, or sender ownership.
- Reject unverified webhook events.
- Reconcile ambiguous submissions before retrying.
- Stop future sends after applicable complaints, opt-outs, or hard failures.
- Revoke the narrowest credential and suspend the affected boundary after a
  suspected compromise.

Test recipient-scope bypass, approval tampering, concurrent budget exhaustion,
duplicate work, webhook replay, cross-tenant access, and independent
suspension.

Referenced files: 2