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, metadata, contact-rule filter modes mail_filter_mode / phone_filter_mode / imessage_filter_mode), 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 |
| iMessage | Send 1:1 messages or dedicated-outbound groups with identity.send_imessage(to=[...]), reply or retry failed creation by conversation_id, and opt groups into message/conversation lists with include_groups=True. IMessageGroupCreationStatus and group_creation_status expose creating, not_created, or ready; failed attempts stay in the same conversation. send_style works on group creation and replies and can accompany media. Existing message-ID reaction methods support inbound group messages, with nullable reaction assignment_id. Group read receipts and typing are not supported |
| 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, search, delete. The per-mailbox filter_mode update is deprecated — set mail_filter_mode on the identity instead |
| Phone numbers (admin) | Provision local numbers (with optional state), update incoming-call action (webhook / auto_accept / auto_reject), transcript search, release |
| Contact rules | Identity-keyed mail (exact email / domain) and phone (exact E.164) allow/block rules, addressed by agent handle (mail_identity_contact_rules / phone_identity_contact_rules, plus identity.create_mail_contact_rule(...) etc.); whitelist vs blacklist via the identity's mail_filter_mode / phone_filter_mode; action updates and duplicate-rule handling. The per-mailbox / per-number rule resources are deprecated |
| 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 | Per-identity signing keys — create / rotate / status by agent handle (signing_keys.create_or_rotate / get_status, plus identity.create_signing_key() / identity.get_signing_key_status()); the org-level signing key is deprecated. The first webhook subscription created for a keyless identity returns its signing secret once. 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] ({id, name, memories: list[str]}) and data.agent_identities: list[WebhookAgentIdentity] (always present, possibly empty); inbound-call payloads expose the same plural pair at top level. Contact matches are organization-wide; agent-identity matches retain identity visibility filtering |
| Error handling | InkboxAPIError with status code and structured detail; narrower DuplicateContactRuleError subclass |
| 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