TypeScript SDK Skill
This skill teaches your coding agent how to use the @inkbox/sdk TypeScript package. Once installed, the agent automatically knows the correct imports, initialization patterns, and method signatures for the entire SDK surface — identities, email, phone, SMS/MMS, vault, contacts, notes, contact rules, TOTP, tunnels, whoami, and webhooks.
What your agent learns
| Feature | Operations |
|---|---|
| Identities | Create, get, list, update (rename / pause / activate), refresh, delete |
| Channel management | Provision phone numbers, assign and unlink mailboxes and phone numbers |
| Agent self-signup | Static Inkbox.signup / verifySignup / resendSignupVerification / getSignupStatus — claim flow and restrictions |
| Email — send | Text, HTML, CC/BCC, base64 attachments, threaded replies via inReplyToMessageId |
| Email — read | Paginated iterEmails / iterUnreadEmails, filter by direction, fetch full threads oldest-first, mark read |
| Email — threads | Thread folders (inbox / spam / archive / blocked), per-thread folder updates, folder listing |
| Phone calls | Place outbound calls with client WebSocket audio, list history, transcript segments per party |
| Text messages (SMS/MMS) | Send 1:1 SMS/MMS and beta group MMS (identity.sendText({ to? | conversationId?, text?, mediaUrls? })), list and filter, single message with MMS media, conversation summaries with includeGroups and latestHasMedia, per-conversation messages by UUID or 1:1 remote key, mark read, admin search / update / delete. Some carriers may reject group chats or MMS from 10DLC numbers |
| Vault — secrets | Initialize with client-side encryption, unlock, CRUD all payload types (login, api_key, key_pair, ssh_key, other), metadata-only listing without unlock |
| Vault — identity-scoped | identity.getCredentials() with typed per-type accessors (getLogin, getApiKey, getSshKey, getKeyPair), filtered by access rules |
| TOTP | Store inside LoginPayload.totp, parse otpauth:// URIs, generate codes client-side, set / remove on existing logins |
| Mailboxes (admin) | List, get, update display name / filter mode, search, delete, filter-mode change notices |
| Phone numbers (admin) | Provision local numbers (with optional state), update incoming-call action (webhook / auto_accept / auto_reject), transcript search, release |
| Contact rules | Mail (exact email / domain) and phone (exact E.164), whitelist vs blacklist modes, status toggle, duplicate-rule handling |
| Contacts | CRUD with emails / phones / addresses, reverse-lookup variants, per-identity or wildcard access grants, bulk vCard import (≤5 MiB, ≤1000 cards), vCard 4.0 export |
| Notes | CRUD free-form notes, list and filter, per-identity access grants (no wildcard) |
| Whoami | Inspect caller's auth type (API key vs Inkbox Console user session), organization ID, API-key subtype constants for admin vs agent-scoped branching |
| Webhooks | Rotate signing keys; verify incoming requests via HMAC-SHA256 over {requestId}.{timestamp}.{body}; typed receiver-side payloads (MailWebhookPayload, TextWebhookPayload, PhoneIncomingCallWebhookPayload) with event_type discrimination across all six mail events and all five text.* lifecycle events; mail events carry data.contacts: WebhookMailContact[] ({bucket, address, id, name}, sparse, with MailContactBucket = "from" | "to" | "cc" | "bcc") plus bcc_addresses on outbound; text events carry conversation_id, sender_phone_number, outbound recipients[], and top-level recipient_phone_number for group lifecycle events, plus plural data.contacts: WebhookContact[] and data.agent_identities: WebhookAgentIdentity[] (always present, possibly empty); inbound-call payloads expose the same plural pair at top level |
| Error handling | InkboxAPIError with status code and structured detail; narrower DuplicateContactRuleError and RedundantContactAccessGrantError subclasses |
| Tunnels | connect(inkbox, { tunnelId, forwardTo | handler, wsHandler? }) from @inkbox/sdk/tunnels/connect for a public my-agent.inkboxwire.com URL; URL forwarding or Fetch-API + WebSocket handlers; edge vs passthrough TLS. Read-only API on tunnels (list / get / update) plus connect() and signCsr() for passthrough; tunnel creation and deletion happen through the identity surface. Node ≥ 22, POSIX-only data plane. |
Install
bash