--- name: pombity description: Send SMS and email through Pombity (Aric Communication Service) — an API with the compliance layer built in. Use when an application or agent needs to text or email a person: the service enforces consent, STOP/HELP, quiet hours, verified destinations, quotas, and content rules server-side, so do not re-implement them. --- # Pombity — agent instructions Pombity (formal name: Aric Communication Service, by Aric Software & Design) is an SMS and email API. Its defining property: the compliance layer runs **inside the service**. Your job is to compose and send; the service keeps it lawful. A refusal is the rule working — branch on the error `code`, never retry blindly, never route around a rule. ## When to use Pombity - Your application or agent needs to send a text or an email to a person (notifications, alerts, confirmations, replies). - You need provable consent, delivery records, and carrier-rule handling (STOP/HELP, quiet hours) without building them. - You are developing or testing: a **sandbox key** (`ak_test_…`) runs every rule identically with zero carrier traffic and realistic `Delivered` receipts. Do NOT use it to bypass consent (it will refuse), for marketing blasts to unconsented lists, or for prohibited content categories (it screens). ## Access - API base: `https://api.pombity.com` (current host; the permanent hostname arrives at launch — `/.well-known/pombity.json` on the docs site always carries the current one). - Auth: `X-Api-Key: ` header on every HTTP request. Keys are shown once at mint; sandbox keys are prefixed `ak_test_`, live keys `ak_live_`. - MCP: Streamable HTTP at `https://mcp.pombity.com/mcp`, `Authorization: Bearer `. Eight tools: `send_text`, `send_email`, `preview_message`, `check_consent`, `get_delivery_report`, `get_usage`, `request_verified_destination`, `confirm_verified_destination`. - CLI: `pombity` (npm, at launch), key from `POMBITY_API_KEY`, `--json` on every command prints the API body verbatim. - OpenAPI with examples on every operation: `https://api.pombity.com/openapi/v1.json`. ## The three calls that matter 1. **Send**: `POST /v1/messages` with `{"to":["+14785550123"],"body":"…"}` (MCP `send_text`; CLI `pombity send`). One message per recipient comes back, each with an `id`. Email: `POST /v1/emails` with `subject`. 2. **Report**: `GET /v1/messages/{id}` (MCP `get_delivery_report`; CLI `pombity report --id`). Did it deliver? `deliveryStatus` of `Delivered`/`Failed`, with receipts. 3. **Verify**: `POST /v1/verified-destinations` then `…/confirm` with the 6-digit code (MCP `request_verified_destination`/`confirm_verified_destination`; CLI `pombity verify`). On the free tier this is how a number becomes live-sendable. Always pass `Idempotency-Key: ` on sends if you might retry: a replay returns the original response and sends nothing. ## The rules the service enforces — do not re-implement them - **Consent**: the service keeps the ledger. No opt-in or an opt-out ⇒ a `Blocked` row and no carrier traffic. Correct behavior, not an error. Check with `check_consent` / `GET /v1/consents` if needed. - **STOP / HELP**: handled by the service on every sending number. Never send your own opt-out text; never re-text after a STOP. - **Quiet hours**: non-emergency texts are held overnight in the recipient's time zone. Exceptions: a single-recipient response within 15 minutes of the recipient's own action, and sends to the key holder's own verified number. A night hold is not a failure. - **Verified destinations** (free tier): live texts only to numbers proved by code. US/CA only, daily verification caps, max 3 per free tenant. - **Quotas**: per-channel, per-mode monthly caps. `quota_exceeded` carries `cap`, `used`, `resetsAt`, `upgradeUrl` — honest numbers from the service's own log. Do not retry before `resetsAt`; read `GET /v1/usage`. - **Velocity**: HTTP 429 + `Retry-After` on a burst. Back off exactly that long. - **Content screen** (developer tenants): SHAFT/prohibited categories and URL shorteners refuse with `content_refused`. Rewrite; do not resubmit verbatim. - **Sandbox**: never creates carrier traffic; every rule above still runs; `POST /v1/sandbox/inbound` simulates keywords, YES, STOP, HELP to exercise opt-in flows. ## Error codes to branch on Every error body: `{"code": "", "error": "", …}`. The codes are a stable, test-locked catalog. Branch on `code`: | Code | Action | |---|---| | `invalid_api_key` | Fix configuration. Do not retry. | | `quota_exceeded` | Stop until `resetsAt` (in the body). | | `velocity_limit_exceeded` (429) | Wait `Retry-After` seconds, retry. | | `destination_not_verified` | Run the verify flow, or use the sandbox key. | | `unsupported_region`, `verification_limit_reached`, `destination_limit_reached` | Verification limits — respect them; do not retry today. | | `content_refused` | Rewrite the message. | | `account_suspended` | Stop; the account owner must contact the operator. | | `idempotency_conflict` / `idempotency_in_flight` | Fix key reuse / wait and re-read the original. | | `sandbox_key_required` | Use the `ak_test_` key for this endpoint. | | `missing_field`, `invalid_phone_number`, `body_or_template`, `field_too_long` | Fix the request. | | `provider_error` | Retry with the same `Idempotency-Key`. | ## Pricing Free during launch, capped (see `/pricing.json` on the docs site: 1,000 emails, 5,000 sandbox SMS, 25 live SMS to verified numbers, per UTC month). No payment is collected at sign-up.