inkbox-ai/inkbox/inkbox-python

pip install inkbox

from inkbox import Inkbox
with Inkbox(api_key="ApiKey_...") as inkbox:
    ...

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  (.permissions, .communication_policy, .facts, .correspondence, .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_mail_contact_rules() / .create_mail_contact_rule(...) / .get_/.update_/.delete_
├── .list_phone_contact_rules() / .create_phone_contact_rule(...) / ...  (writes require admin credentials)
├── .get_signing_key_status() / .create_signing_key()
├── .list_contact_communication_policies() → ContactCommunicationPolicyPage
├── mail methods             (requires assigned mailbox)
├── phone methods            (requires assigned phone number)
└── text methods             (requires assigned phone number)

identity = inkbox.create_identity("sales-agent")
identity = inkbox.get_identity("sales-agent")
identities = inkbox.list_identities()  # → list[AgentIdentitySummary]
identity.update(display_name="Sales assistant")
identity.refresh()                       # re-fetch from API, updates cached channels
identity.delete()                        # cascades: mailbox + tunnel + phone-number release

# 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="local", state="NY")  # local only; toll_free is rejected (422)
print(phone.number)                      # e.g. "+12125551234"
# Release the phone number (vendor + local)
identity.release_phone_number()

from inkbox import MailImportFormat
created = inkbox.mailboxes.imports.create(
    email,
    source_format=MailImportFormat.AUTO,
    original_addresses=["old@example.com"],
)
inkbox.mailboxes.imports.upload(created.upload, "archive.mbox")
inkbox.mailboxes.imports.start(email, str(created.job.id))
job = inkbox.mailboxes.imports.wait(email, str(created.job.id), poll_interval=5)

sent = identity.send_email(
    to=["user@example.com"],
    subject="Hello",
    body_text="Hi there!",          # plain text (optional)
    body_html="<p>Hi there!</p>",   # 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": "<base64>",
    }, {
        "filename": "chart.png",        # inline image: set content_id and
        "content_type": "image/png",    # reference it from body_html as
        "content_base64": "<base64>",   # <img src="cid:chart">. needs body_html
        "content_id": "chart",          # + image/*, unique per send; not on forwards.
    }],
    track_opens=True,               # optional; embed a tracking pixel
)
# track_opens tracks sends only when an HTML body is present. Opens
# surface on the returned Message as sent.first_opened_at / sent.open_count
# (approximate — proxy prefetch inflates it, the per-window debounce
# collapses repeats, so it can read above or below the true count; prefer
# first_opened_at. pixels can also raise spam scores).
#
# send_email / reply_all_email / forward_email all raise
# StorageLimitExceededError (402) when the mailbox is at its storage cap —
# see "Storage cap (402)" below.

from inkbox import DraftRecipients
draft = identity.create_email_draft(
    subject="Work in progress",
    idempotency_key="draft-create-2026-08-19-1",
)
for saved in identity.iter_email_drafts():
    print(saved.id, saved.generation)
current = identity.get_email_draft(draft.id)
current = identity.update_email_draft(
    current.id,
    generation=current.generation,
    recipients=DraftRecipients(to=["user@example.com"]),
    subject=None,  # explicit null clears; omission leaves unchanged
)
current = inkbox.drafts.add_attachments(
    identity.email_address,
    current.id,
    generation=current.generation,
    attachments=[{
        "filename": "notes.txt",
        "content_type": "text/plain",
        "content_base64": "bm90ZXM=",
    }],
)
part = current.attachment_metadata[0]
content = inkbox.drafts.download_attachment(
    identity.email_address, current.id, part.part_index, generation=current.generation
)
current = inkbox.drafts.remove_attachment(
    identity.email_address, current.id, part.part_index, generation=current.generation
)
copy = identity.duplicate_email_draft(current.id, generation=current.generation)
identity.delete_email_draft(copy.id, generation=copy.generation)
sent = identity.send_email_draft(current.id, generation=current.generation)

# 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)
identity.mark_emails_unread(ids)   # batch counterpart
# Note: fetching a single inbound message by id (inkbox.messages.get) with
# an API key marks it read server-side; iterating does not, so
# mark_emails_read is the way to clear unread for list-only workflows.
# is_read (agent consumed via API) is distinct from first_opened_at
# (recipient's mail client loaded the tracking pixel).
# Get full thread (oldest-first)
thread = identity.get_thread(msg.thread_id)
for m in thread.messages:
    print(f"[{m.from_address}] {m.subject}")

from inkbox import ThreadFolder
# Thread.folder / ThreadDetail.folder is always one of the four values above.

from inkbox import StorageLimitExceededError
try:
    identity.send_email(to=["user@example.com"], subject="Hi", body_text="…")
except StorageLimitExceededError as e:
    print(e.message)      # human sentence, includes the limit
    print(e.limit_bytes)  # e.g. 2147483648 (2 GiB)
    print(e.upgrade_url)  # console billing page
    # Free space — reclaim is immediate — or upgrade the plan:
    inkbox.messages.delete(identity.email_address, "<message-uuid>")
    inkbox.threads.delete(identity.email_address, "<thread-uuid>")