SDK v0.1.0 by rayruizhiliao · Pull Request #2 · VectorlyApp/inkbox

rayruizhiliao · 2026-03-12T18:28:02Z

Initial SDK (v0.1.0)

To test and run examples locally

cd inkbox/examples/python
pip install -e ../../python  #or with uv: uv pip install -e ../../python
# then run any example:
INKBOX_API_KEY=ApiKey_... MAILBOX_ADDRESS=agent@inkboxmail.com python agent_send_email.py

cd inkbox/typescript && npm run build
cd ../examples/typescript
INKBOX_API_KEY=ApiKey_... MAILBOX_ADDRESS=agent@inkboxmail.com node --experimental-strip-types agent-send-email.ts

- pip install inkbox-mail → inkbox - from inkbox_mail → from inkbox.mail - @inkbox/mail → @inkbox/sdk - Python examples: async/await → synchronous (matches actual SDK) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Python: inkbox.phone package with InkboxPhone client, 5 models, 4 resource classes (numbers, calls, transcripts, webhooks) - TypeScript: @inkbox/sdk/phone subpath export with matching resources - 16 methods covering: provision/release numbers, place/list/get calls, list transcripts, search transcripts, webhook CRUD Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Python: uv sync --extra dev installs ruff/pytest/pytest-cov - TypeScript: remove cache config (no package-lock.json) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…mode - stream_url now falls back to phone number's default_stream_url - call_mode renamed to pipeline_mode to match actual API field name - Updated both Python and TypeScript SDKs + tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

dimavrem22 · 2026-03-12T21:42:59Z

python/README.md

we should either make this a full read me or remove it? but probably make it a detailed docs. and then we would prob also need to add one for type script

updated in commit 279c72d

dimavrem22 · 2026-03-12T22:02:00Z

high level thought: I feel like 3 separate clients are a little confusing to manage. Can we put all clients under a single InkboxClient like this:

this will let us to things like in the future:

  inkbox = Inkbox(api_key="ApiKey_...")                                                                                                                                                                                         
                                                            
  agent = inkbox.identities.create(agent_handle="support-bot")                                                                                                                                                                  
                                                                                                                                                                                                                                
  # Provision and link
  agent.assign_mailbox(display_name="Support Bot")
  agent.assign_phone_number(type="toll_free")

  # Send directly from the agent
  agent.send_email(
      to=["customer@example.com"],
      subject="Your order has shipped",
      body_text="Tracking number: 1Z999AA10123456784",
  )

  agent.place_call(
      to_number="+18005559999",
      stream_url="wss://my-app.com/voice",
  )

  # Read inbox
  for message in agent.messages():
      print(message.subject)

  # Search transcripts
  transcripts = agent.search_transcripts(q="refund")

  inkbox.close()

dimavrem22 · 2026-03-12T22:09:40Z

lets include a built in method to help verify that requests that we sent come from us:

dimavrem22 · 2026-03-13T18:59:12Z

README.md

# Provision and link channels in one call each identity.assign_mailbox(display_name="Support Bot") identity.assign_phone_number(type="toll_free")

to me assign sounds like we are attaching an existing object. maybe something like "provision"?

updated in commit 58c2743

Below are updated channel methods for AgentIdentity:

create_mailbox(display_name=) — create + link a new mailbox
assign_mailbox(mailbox_id) — link an existing mailbox
unlink_mailbox() — unlink (doesn't delete)
provision_phone_number(type=, state=) — provision + link a new phone number
assign_phone_number(phone_number_id) — link an existing phone number
unlink_phone_number() — unlink (doesn't release)

dimavrem22 · 2026-03-13T19:01:00Z

typescript/README.md

+// Place an outbound call
+await identity.placeCall({
+  toNumber: "+18005559999",
+  streamUrl: "wss://my-app.com/voice",
+});


lets move this under all mail methods and add then add examples for reading / searching transcripts for consistency with mail (same for python)

Updated: https://github.com/VectorlyApp/inkbox/tree/phone/python, https://github.com/VectorlyApp/inkbox/tree/phone/typescript

dimavrem22 · 2026-03-13T19:02:16Z

README.md

self hosting? Should the base url be removed?

Removed in the current README: https://github.com/VectorlyApp/inkbox/tree/phone

dimavrem22 · 2026-03-13T19:04:12Z

python/README.md

+print(mailbox.email_address)
+print(phone.number)



Suggested change

print(mailbox.email_address)

print(phone.number)

Updated: https://github.com/VectorlyApp/inkbox/tree/phone/python, https://github.com/VectorlyApp/inkbox/tree/phone/typescript

Note you can still retrieve org-level mailboxes or phones

dimavrem22 · 2026-03-13T19:06:45Z

python/README.md

+# Iterate inbox (paginated automatically)
+for msg in identity.messages():


how does this work? iterate through all messages in the mailbox ever? should we have some methods like
unread_count? or only parse those that are unread? also can the agent pull targeted messages from a thread for example?

Updated comment:

Rename messages(page_size=, direction=) to emails(). Instead add get_unread_emails(), get_emails_by_thread()

Renamed messages(page_size=, direction=) to iter_emails(page_size?, direction?) to clarify it's an iterator for emails in commit 58c2743

Added iterUnreadEmails(pageSize?, direction?) and markEmailsRead(messageIds) in commit 94db06f

Added get_thread(self, thread_id: str) in commit d2ec5fd

dimavrem22 · 2026-03-13T19:09:53Z

python/README.md

-print(hook.secret)  # save this
+print(call.status, call.rate_limit.calls_remaining)
+
+# Full-text search across transcripts


shodul also probably be able to get transcript of a call by id

Updated comment:

Remove search_transcripts(q, party=, limit=), and transcripts(call_id) already exists

Updated in commit 581d790

calls → list_calls

transcripts → list_transcripts

search_transcripts removed

dimavrem22 · 2026-03-13T21:21:57Z

README.md

+# Inkbox SDK

-Official SDKs for the [Inkbox Mail API](https://inkbox.ai) — API-first email for AI agents.
+Official SDKs for the [Inkbox API](https://inkbox.ai) — API-first communication infrastructure for AI agents (email, phone, identities).


should this point to docs?

yes, updated in commit 71b6ac0

dimavrem22 and others added 10 commits March 10, 2026 16:01

phone, unit tests, test scripts

26f467a

Fix CI: use uv sync --extra dev and remove npm cache config

5c93d0c

- Python: uv sync --extra dev installs ruff/pytest/pytest-cov - TypeScript: remove cache config (no package-lock.json) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix lint: remove unused import and variable

ea08602

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix lint: move import to top of file in test script

29b3e0a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove auto-provisioning from test scripts, exit if no numbers attached

41d7a87

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: updated endpoints

0112ff9

feat: mit license

2c88746

rayruizhiliao requested a review from dimavrem22 March 12, 2026 18:28

rayruizhiliao added 10 commits March 12, 2026 14:36

rm scriprts and fix tests

3a2d12d

feat: examples

49cae6c

add more tests

ffa4ac5

include ts tests

fe1d63b

update api key placeholders

477e298

add more examples

e6aa25a

make examples more relevant

cdee0ee

adapt endpoint updates

4d0f59d

update signing keys

8bbcd8d

fix tests

ddf11f9

rayruizhiliao marked this pull request as ready for review March 12, 2026 21:03

rayruizhiliao added 4 commits March 12, 2026 17:19

fix more tests

a90b345

fix tests

a7f4a7e

fix ts tests

1fb0f95

fix more tests

03fe84c

dimavrem22 reviewed Mar 12, 2026

View reviewed changes

update readmes

8583a93

rayruizhiliao added 6 commits March 13, 2026 12:52

improve abstraction

1417dc3

update readme

789d547

restructure typescripts

d680da8

fix tests

b2332f4

feat: call and transcripts methods

82dcae8

feat: update readme files

bf463f9

dimavrem22 reviewed Mar 13, 2026

View reviewed changes

rm stale resources

cc7e8e1

dimavrem22 reviewed Mar 13, 2026

View reviewed changes

rayruizhiliao added 12 commits March 13, 2026 15:17

seperate create and assing

58c2743

update email methods

dcfc32a

rename agent to agent_identity

d728cc0

feat: more email methods

94db06f

feat: get thread

d2ec5fd

update phone methods

581d790

simplify signing key verification

a13aee3

rm examples

4eee438

update readme

6aaf350

update readme

05f890f

fix: inconsistency with api

9c57463

token readme

c80fa3a

dimavrem22 reviewed Mar 13, 2026

View reviewed changes

update reamde

71b6ac0

dimavrem22 approved these changes Mar 13, 2026

View reviewed changes

rayruizhiliao merged commit ba60e8d into main Mar 13, 2026
2 checks passed

dimavrem22 deleted the phone branch March 13, 2026 21:34

		# Iterate inbox (paginated automatically)
		for msg in identity.messages():

Conversation

rayruizhiliao commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dimavrem22 commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dimavrem22 commented Mar 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rayruizhiliao commented Mar 12, 2026 •

edited

Loading

dimavrem22 commented Mar 12, 2026 •

edited

Loading