Python SDK Skill
This skill teaches your coding agent how to use the inkbox Python 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 | Class methods Inkbox.signup / verify_signup / resend_signup_verification / get_signup_status — claim flow and restrictions |
| Email — send | Text, HTML, CC/BCC, base64 attachments, threaded replies via in_reply_to_message_id |
| Email — read | Paginated iter_emails / iter_unread_emails, 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.send_text(to=... | conversation_id=..., text=None, media_urls=None)), list and filter, single message with MMS media, conversation summaries with include_groups and latest_has_media, 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.credentials with typed per-type accessors (get_login, get_api_key, get_ssh_key, get_key_pair), 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 {request_id}.{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: list[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: list[WebhookContact] and data.agent_identities: list[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 | inkbox.tunnels.connect(tunnel_id=..., forward_to=...) for a public my-agent.inkboxwire.com URL; URL forwarding or in-process ASGI app; edge vs passthrough TLS. Read-only API on tunnels (list / get / update) plus connect() and sign_csr() for passthrough; tunnel creation and deletion happen through the identity surface. POSIX-only data plane. |
Install
bash