Imported from zwright8/OpenClaw-Code (
skills/generated/shards/tools04/0391-postmark-connector/SKILL.md). Install upstream withnpx skills add zwright8/OpenClaw-Code --skill 0391-postmark-connector. Copyright stays with the author.
Postmark Connector
Quick Reference
| Field | Value |
|---|---|
| Skill ID | 391 |
| Provider | Postmark |
| Operation | Connector |
| Domain | External SaaS integrations |
| Runtime archetype | integration-connector |
| Core method | auth-scoped api mediation |
| Primary artifact | postmark-connection-trace-bundle |
| Routing tag | postmark:connector |
| Mutating | yes |
| Release cycles | 2 |
Why This Skill Exists
We need this skill because Postmark workflows degrade when auth, schema, and side-effect handling drift when integrations are run ad hoc. This specific skill turns Postmark Connector into a deterministic, auth-checked workflow for unified read/write connector for postmark apis and data..
Trigger Checklist
- The task explicitly requires
Postmark Connectorrather than generic brainstorming. - The provider tenant, workspace, or environment is known before execution begins.
- Credential reuse has been checked before asking for new secrets.
- Success criteria, side effects, and handoff owner are clear.
- If the run mutates provider state, the relevant approval gates are available.
Auth & Access Profile
| Field | Value |
|---|---|
| External auth required | yes |
| API key likely required | no |
| Protocols | HTTPS/REST |
| Mutating | yes |
| Webhook capable | no |
| Auth Mode | Kind | Env Hints | Validation |
|---|---|---|---|
| OAuth client or delegated session | oauth2 |
POSTMARK_CLIENT_ID, POSTMARK_CLIENT_SECRET |
Reuse an active delegated session or validate the client credentials with a lightweight identity call. |
| Access token or personal access token | token |
POSTMARK_TOKEN, POSTMARK_ACCESS_TOKEN |
Validate the token with the smallest read-only endpoint that proves scope and tenancy. |
Inputs (contract)
| Input | Type | Required | Source |
|---|---|---|---|
| auth context | signal | yes | operator or upstream tool |
| resource scope | signal | yes | operator or upstream tool |
| request contract | signal | yes | operator or upstream tool |
Outputs (contract)
| Output | Type | Guaranteed | Consumer |
|---|---|---|---|
| postmark-connection-trace-bundle | structured-artifact | yes | next workflow or operator |
| postmark-connection-trace-bundle-scorecard | scorecard | yes | reviewer |
| postmark-connection-trace-bundle-handoff | handoff-packet | yes | downstream owner |
Step-by-Step Implementation Guide
- Define the objective, target resources, and permitted side effects for Postmark Connector, then confirm the smallest read-only probe that proves access to Postmark.
- Resolve credential reuse first, validate identity and scopes, and only ask for new secrets if the existing auth context is missing, invalid, or expired.
- Specify the request and response contract for unified read/write connector for postmark apis and data., including idempotency rules and provider rate-limit posture.
- Execute the read-only probe, widen to the minimum required write scope, and capture deterministic request/response traces for every call.
- Run integration and regression checks that cover auth expiry, scope mismatch, and rate limiting before approving downstream automation reuse.
- Publish a connection bundle with scopes, created artifacts, and next-action guidance for any workflow that depends on this provider session.
Operational Runbook
Preflight
- Verify credential reuse candidates before asking for new secrets.
- Start with the minimum read-only probe that proves identity, scope, and rate-limit posture.
Execution
- Execute the smallest valid API operation first, then widen scope only after validation passes.
- Capture endpoint, request shape, and response identifiers in the handoff bundle.
Recovery
- On auth or permission failure, stop writes, preserve diagnostics, and fall back to read-only verification.
- On mutating error, revoke the write session and reconcile resulting state before retry.
Handoff
- Return the validated connection state, scopes used, and any newly created IDs or URLs.
- Document whether the session is safe for downstream automation or requires human re-approval.
Validation Gates & Test Matrix
| Gate | Purpose | On Fail |
|---|---|---|
| auth-preflight | Validate credential presence, scope, and environment before work begins. | block execution |
| schema-contract-check | Ensure required signals and payload shapes remain valid. | quarantine and request correction |
| policy-approval-check | Verify the declared approval gates before mutating or publishing state. | pause or route to human review |
| reliability-check | Confirm retries, rollback, and checkpoint readiness. | rollback or fail closed |
- Required validation suites:
unit,integration,regression-baseline
Failure Modes & Recovery Playbook
| Code | Trigger | Action |
|---|---|---|
E_AUTH_CONTEXT |
Missing, invalid, or expired provider credentials. | Fail closed, capture auth diagnostics, and request corrected auth context. |
E_SCOPE_MISMATCH |
Credential exists but required scopes or permissions are absent. | Block mutating operations and route to human review with exact missing scopes. |
E_PROVIDER_RATE_LIMIT |
Provider rejects calls due to throttling or abuse detection. | Apply retry budget, reduce concurrency, and resume with read-only verification. |
Tool Call Implementation
- Reuse existing credentials first. Check environment variables, secure stores, and active sessions before prompting.
- Start with the smallest authenticated read or validation call that proves identity and scope.
- Preserve request, response, and approval traces in
postmark-connection-trace-bundleso downstream owners do not need to rediscover context. - If any auth, contract, or approval gate fails, halt execution and attach remediation guidance instead of guessing.
Credential Reuse Policy
- Reuse valid provider credentials by default and prefer tenant-scoped sessions over newly created secrets.
- Prompt for credentials only when they are missing, invalid, expired, or point at the wrong environment.
- For webhook flows, validate the signing secret against a known sample before accepting live traffic.
Guardrails
- quality: Require an auth preflight and read-only probe before any write-capable call. (
auth-preflight+read-probe) - reliability: Throttle retries and reconcile provider state after write failures. (
retry-budget+state-reconcile) - compliance: Enforce least privilege and preserve the scopes used for the run. (
scope-audit)
Acceptance Checklist
- Credential preflight and scope validation completed successfully.
- Required validation suites ran and all fail-closed gates passed.
- postmark-connection-trace-bundle, scorecard, and handoff packet were produced.
- Any mutations, approvals, or rollbacks are reflected in the artifact bundle.
Anti-Patterns
- Do not ask for new credentials before checking reusable auth context.
- Do not skip the read-only or dry-run validation step for mutating work.
- Do not proceed when approval gates, signing secrets, or rollback checkpoints are missing.
- Do not hand off partial or ambiguous provider state as complete.
Handoff Contract
- Produces:
postmark-connection-trace-bundle, execution scorecard, approval trace, and next actions. - Consumes:
auth context,resource scope,request contract. - Readiness rule: release only after auth, contract, approval, and reliability gates all pass.
- Downstream hint: route to
postmark:connectorconsumers with approval and credential context attached.
Observability & Continuous Improvement
- SLO: >=99.7% successful runs per 7-day window
- Error budget: <=0.3% critical failures per 7-day window
- Alert triggers:
- credential validation failures exceed baseline
- schema or contract regressions persist for two consecutive runs
- critical posture or rollback events exceed tolerance
- Primary outcome metric:
auth success rate - Secondary metrics:
request validation pass rate,side-effect correctness - Review cadence:
weekly
