# Inkbox Python > Use when writing Python code that imports from `inkbox`, uses `pip install inkbox`, or when adding email, phone, text/SMS, iMessage, contacts, notes, contact rules, vault, tunnels, or agent identity features using the Inkbox Python SDK. - **Type:** Skill - **Install:** `agentstack add skill-inkbox-ai-inkbox-inkbox-python` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [inkbox-ai](https://agentstack.voostack.com/s/inkbox-ai) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [inkbox-ai](https://github.com/inkbox-ai) - **Source:** https://github.com/inkbox-ai/inkbox/tree/main/skills/inkbox-python - **Website:** https://inkbox.ai/docs ## Install ```sh agentstack add skill-inkbox-ai-inkbox-inkbox-python ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Inkbox Python SDK API-first communication infrastructure for AI agents — email, phone, encrypted vault, and identities. ## Install & Init ```python pip install inkbox ``` Always use the context manager — it manages the underlying HTTP session: ```python from inkbox import Inkbox with Inkbox(api_key="ApiKey_...") as inkbox: ... ``` Constructor: `Inkbox(api_key, base_url="https://inkbox.ai", timeout=30.0)` ## Core Model ``` Inkbox (admin-only client) ├── .create_identity(handle) → AgentIdentity ├── .get_identity(handle) → AgentIdentity ├── .list_identities() → list[AgentIdentitySummary] ├── .mailboxes → MailboxesResource ├── .phone_numbers → PhoneNumbersResource ├── .texts → TextsResource ├── .imessages → IMessagesResource ├── .imessage_contact_rules → IMessageContactRulesResource ├── .mail_identity_contact_rules → MailIdentityContactRulesResource (keyed by agent_handle) ├── .phone_identity_contact_rules → PhoneIdentityContactRulesResource (keyed by agent_handle) ├── .signing_keys → SigningKeysResource (per-identity: create_or_rotate/get_status) ├── .mail_contact_rules → MailContactRulesResource (DEPRECATED — per-mailbox) ├── .phone_contact_rules → PhoneContactRulesResource (DEPRECATED — per-number) ├── .sms_opt_ins → SmsOptInsResource ├── .contacts → ContactsResource (.access, .vcards) ├── .notes → NotesResource (.access) ├── .vault → VaultResource ├── .whoami() → WhoamiResponse └── .create_signing_key() → SigningKey (DEPRECATED — org-level; use .signing_keys) AgentIdentity (identity-scoped helper) ├── .mailbox → IdentityMailbox | None ├── .phone_number → IdentityPhoneNumber | None ├── .mail_filter_mode / .phone_filter_mode → FilterMode ├── .credentials → Credentials (requires vault unlocked) ├── .list_access() → list[IdentityAccess] ├── .grant_access(viewer_id|None) → IdentityAccess ├── .revoke_access(viewer_id) → None ├── .list_mail_contact_rules() / .create_mail_contact_rule(...) / .get_/.update_/.delete_ ├── .list_phone_contact_rules() / .create_phone_contact_rule(...) / ... (requires phone number) ├── .get_signing_key_status() / .create_signing_key() ├── mail methods (requires assigned mailbox) ├── phone methods (requires assigned phone number) └── text methods (requires assigned phone number) ``` An identity must have a channel assigned before you can use mail/phone methods. If not assigned, an `InkboxError` is raised with a clear message. ## Agent Signup For the full agent self-signup flow (register, verify, check status, restrictions, and direct API examples), read the shared reference: > **See:** `skills/inkbox-agent-self-signup/SKILL.md` Python SDK methods: `Inkbox.signup(...)`, `Inkbox.verify_signup(api_key, ...)`, `Inkbox.resend_signup_verification(api_key)`, `Inkbox.get_signup_status(api_key)`. ## Identities ```python identity = inkbox.create_identity("sales-agent") identity = inkbox.get_identity("sales-agent") identities = inkbox.list_identities() # → list[AgentIdentitySummary] identity.update(new_handle="new-name") # rename identity.update(status="paused") # or "active" identity.refresh() # re-fetch from API, updates cached channels identity.delete() # cascades: mailbox + tunnel + phone-number release ``` ## Channel Management ```python # Identity is created with a mailbox AND tunnel atomically — both come back on the response print(identity.email_address) # e.g. "sales-agent@inkboxmail.com" print(identity.tunnel.public_host) # e.g. "sales-agent.inkboxwire.com" # Phone numbers are still opt-in phone = identity.provision_phone_number(type="toll_free") # or type="local", state="NY" print(phone.number) # e.g. "+18005551234" # Release the phone number (vendor + local) identity.release_phone_number() ``` Mailboxes and tunnels are not separately linkable — they are 1:1 with their owning identity. Use `inkbox.create_identity()` to provision both; use `identity.delete()` to remove both (cascade). ## Identity Visibility Controls which other agent identities can see an identity in API responses. Humans and admins always see every identity. ```python rules = identity.list_access() # list[IdentityAccess] # One wildcard row (viewer_identity_id is None → every active identity sees it), # explicit per-viewer rows, or [] (no agent can see it). identity.grant_access(viewer.id) # grant one viewer identity identity.grant_access(None) # reset to org-wide wildcard identity.revoke_access(viewer.id) # revoke one viewer (keyed by viewer UUID) ``` Granting a viewer against an already-wildcard target raises `RedundantContactAccessGrantError` (409); revoking a non-existent grant raises `InkboxAPIError` (404). ## Mail ### Send ```python sent = identity.send_email( to=["user@example.com"], subject="Hello", body_text="Hi there!", # plain text (optional) body_html="Hi there!", # HTML (optional) cc=["cc@example.com"], # optional bcc=["bcc@example.com"], # optional in_reply_to_message_id=sent.id, # for threaded replies attachments=[{ # optional "filename": "report.pdf", "content_type": "application/pdf", "content_base64": "", }], ) ``` ### Read ```python # Iterate all messages — pagination handled automatically (Iterator[Message]) for msg in identity.iter_emails(): print(msg.subject, msg.from_address, msg.is_read) # Filter by direction for msg in identity.iter_emails(direction="inbound"): # or "outbound" ... # Unread only (client-side filtered) for msg in identity.iter_unread_emails(): ... # Mark as read ids = [msg.id for msg in identity.iter_unread_emails()] identity.mark_emails_read(ids) # Get full thread (oldest-first) thread = identity.get_thread(msg.thread_id) for m in thread.messages: print(f"[{m.from_address}] {m.subject}") ``` ### Thread Folders Threads carry a `folder` field: `inbox`, `spam`, `archive`, or `blocked` (server-assigned, never client-set). ```python from inkbox import ThreadFolder # Thread.folder / ThreadDetail.folder is always one of the four values above. ``` Low-level folder listing / per-thread updates (`list(folder=…)`, `list_folders(email)`, `update(..., folder=…)`) live on `ThreadsResource`. Passing `folder="blocked"` to `update` raises `ValueError` before the HTTP call. ## Phone ```python # Place outbound call — stream audio via WebSocket call = identity.place_call( to_number="+15551234567", client_websocket_url="wss://your-agent.example.com/ws", ) print(call.status) print(call.rate_limit.calls_remaining) # List calls (offset pagination) calls = identity.list_calls(limit=10, offset=0) for c in calls: print(c.id, c.direction, c.remote_phone_number, c.status) # Transcript segments (ordered by seq) for t in identity.list_transcripts(calls[0].id): print(f"[{t.party}] {t.text}") # party: "local" or "remote" ``` ## Text Messages (SMS/MMS) **Outbound SMS limits and gates (current):** - Allowed only from **local** numbers, not toll-free. - **100 recipient sends per phone number per rolling 24h.** A 3-recipient group message counts as 3 recipient sends. A single accepted send may push usage past the cap; the next capped send returns `429 sender_rate_limited`. - New local numbers need **~10-15 min** for 10DLC carrier propagation. `identity.phone_number.sms_status` is `SmsStatus.PENDING` until ready; sends in this window return `409 sender_sms_pending`. - Recipient must have texted **`START`** to any number in the org. Unknown → `403 recipient_not_opted_in`. `STOP` → `403 recipient_opted_out`. Inspect / override consent state via `inkbox.sms_opt_ins` (see below). - **Beta:** Group MMS and conversation sends are beta. Some carriers may reject group chats or MMS from 10DLC numbers even when the sender is ready and recipients have opted in. Customer-managed 10DLC brands/campaigns lift the default per-number cap to the carrier-assigned tier. Toll-free SMS sending is still coming soon. ```python # Send SMS/MMS from this identity's phone number. # Returns a queued TextMessage; final delivery state arrives via any # webhook subscription on the sender's phone number whose event_types # include the text.* lifecycle events. sent = identity.send_text(to="+15551234567", text="Hello from Inkbox") print(sent.id, sent.delivery_status) # SmsDeliveryStatus.QUEUED # Group MMS beta: pass a list of recipients plus optional media URLs. group = identity.send_text( to=["+15551234567", "+15557654321"], text="Hello group", media_urls=["https://example.com/photo.jpg"], ) print(group.conversation_id, group.recipients) # Reply to an existing conversation by UUID. Do not pass "to" with this form. reply = identity.send_text( conversation_id=group.conversation_id, text="Following up in the same conversation.", ) # List text messages (offset pagination) texts = identity.list_texts(limit=20, offset=0) for t in texts: print(t.id, t.direction, t.remote_phone_number, t.text, t.is_read) # Filter by read state unread = identity.list_texts(is_read=False) # Get a single text message text = identity.get_text("text-uuid") print(text.type) # "sms" or "mms" if text.media: # MMS media attachments (temporary signed URLs) for m in text.media: print(m.content_type, m.size, m.url) # List one-to-one conversation summaries; opt into groups explicitly. convos = identity.list_text_conversations(limit=20, include_groups=True) for c in convos: print(c.id, c.participants, c.latest_has_media, c.latest_text) # Get messages in a specific conversation by remote number or conversation UUID. msgs = identity.get_text_conversation("+15551234567", limit=50) # Mark a text as read (identity convenience method) identity.mark_text_read("text-uuid") # Mark all messages in a conversation as read result = identity.mark_text_conversation_read("+15551234567") print(result["updated_count"]) # Admin-only: search, update, delete results = inkbox.texts.search(phone.id, q="invoice", limit=20) inkbox.texts.update(phone.id, "text-uuid", status="deleted") ``` ## iMessage iMessage works differently from SMS: there is no per-identity iMessage number. Recipients connect to an agent identity through a small shared pool of numbers — they ask the triage line to connect them to `@agent_handle`, and that creates an assignment between that one recipient and the identity. Everything agent-facing is keyed by `conversation_id` / `remote_number`; the shared local number is never exposed, and there is **no cold outreach** — you can only message recipients who connected first. Discover the router (triage) line at runtime — it can change, so never hardcode it: ```python triage = inkbox.imessages.get_triage_number() print(triage.number, triage.connect_command) # "+1646...", "connect @your-handle" # Humans connect by texting that command to that number. ``` Reachability is **opt-in per identity** (`imessage_enabled`, default `False`): ```python identity = inkbox.create_identity("my-agent", imessage_enabled=True) # or toggle later identity.update(imessage_enabled=True) # admin-only: flip contact-rule mode (default "blacklist") identity.update(imessage_filter_mode="whitelist") print(identity.imessage_enabled, identity.imessage_filter_mode) ``` Messaging (identity convenience methods; `inkbox.imessages` is the org-level resource with the same operations plus `agent_identity_id` / `is_blocked` filters): ```python # Send to a connected recipient, or reply into a conversation by UUID. sent = identity.send_imessage(to="+15551234567", text="Hello over iMessage") reply = identity.send_imessage( conversation_id=sent.conversation_id, text="With style", send_style="slam", # IMessageSendStyle: confetti, lasers, slam, ... ) print(sent.service, sent.status) # IMessageService.IMESSAGE, IMessageDeliveryStatus.QUEUED # List messages / conversations msgs = identity.list_imessages(limit=20, is_read=False) convos = identity.list_imessage_conversations(limit=20) convo = identity.get_imessage_conversation(sent.conversation_id) # assignment_status tells you whether the recipient is still connected: # anything other than "active" means sends/reactions will be refused # until they reconnect through triage. print(convo.assignment_status) # Who is actively connected to this identity right now (paginated)? connections = identity.list_imessage_assignments(limit=20) for a in connections: print(a.remote_number, a.status, a.created_at) # Tapback reactions. Sends accept the classic six (love, like, dislike, # laugh, emphasize, question); inbound can also be "custom" with the # literal emoji in custom_emoji. identity.send_imessage_reaction(message_id=msgs[0].id, reaction="like") # Live tapbacks come back on message reads, oldest first. for r in msgs[0].reactions or []: print(r.direction, r.reaction, r.custom_emoji) # Read receipts + typing indicator identity.mark_imessage_conversation_read(sent.conversation_id) identity.send_imessage_typing(sent.conversation_id) # Media: upload bytes (max 10 MiB), then send the returned URL (one per message) upload = identity.upload_imessage_media( content=open("photo.jpg", "rb").read(), filename="photo.jpg", content_type="image/jpeg", ) identity.send_imessage(to="+15551234567", media_urls=[upload.media_url]) ``` Contact rules are scoped to the **identity** (not a phone number) because pool numbers are shared infrastructure: ```python from inkbox import IMessageRuleAction rule = inkbox.imessage_contact_rules.create( "my-agent", action=IMessageRuleAction.BLOCK, match_target="+15559999999", ) rules = inkbox.imessage_contact_rules.list("my-agent") inkbox.imessage_contact_rules.update("my-agent", rule.id, status="paused") # admin-only inkbox.imessage_contact_rules.delete("my-agent", rule.id) # admin-only all_rules = inkbox.imessage_contact_rules.list_all() # admin-only, org-wide ``` Inbound messages and reactions arrive via **identity-owned** webhook subscriptions — see Webhooks below. ## SMS Opt-Ins Per-recipient SMS consent state, keyed by `(your org, recipient number)`. The registry is updated automatically when recipients text `START` / `STOP` to any of your numbers (`source="sms"`). Reads are admin-only; writes are admin-only **and** require your org to be on its own active, customer-managed 10DLC campaign (Inkbox-default-campaign orgs share consent state and get `409 customer_campaign_required` on writes — `source="api"` writes record an audit event). ```python from inkbox import SmsOptInStatus # List your org's consent rows, newest-updated first (server caps limit at 200) rows = inkbox.sms_opt_ins.list(limit=50) opted_out = inkbox.sms_opt_ins.list(status=SmsOptInStatus.OPTED_OUT) # Look up one recipient — 404 → InkboxAPIError if no row exists row = inkbox.sms_opt_ins.get("+15551234567") print(row.status, row.source, row.opted_in_at, row.opted_out_at) # Programmatic writes (customer-managed 10DLC campaign only) inkbox.sms_opt_ins.opt_in("+15551234567") inkbox.sms_opt_ins.opt_out("+15551234567") ``` ## Vault Encrypted credential vault with client-side Argon2id key derivation and AES-256-GCM encryption. The server never sees plaintext secrets. Requires `argon2-cffi` and `cryptography` (included as dependencies). ### Initialize ```python # Initialize a new vault (org ID is fetched automatically from the API key) result = inkbox.vault.initialize("my-Vault-key-01!") print(result.vault_id, result.vault_key_id) for code in result.recovery_codes: print(code) # save these immediately — they cannot be retrieved again ``` ### Unlock & Read `` … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [inkbox-ai](https://github.com/inkbox-ai) - **Source:** [inkbox-ai/inkbox](https://github.com/inkbox-ai/inkbox) - **License:** MIT - **Homepage:** https://inkbox.ai/docs Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-inkbox-ai-inkbox-inkbox-python - Seller: https://agentstack.voostack.com/s/inkbox-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.