Release v0.12.0 (sdk-python/v0.12.0)

Author: bird-release[bot]

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.12.0
+
+- Agent mailboxes (inbox.ai): client.mailbox, client.mailbox_receive_rule, client.mailbox_thread, client.mailbox_thread_message
+- Internal pipeline improvements.
+
 ## 0.11.0
 
 - Add the `rejected` WhatsApp message delivery status, returned when the recipient is on the workspace's suppression list.

examples/examples.gen.py

@@ -337,11 +337,142 @@ async def _ex_50() -> None:
 
 
 async def _ex_51() -> None:
+    msg = client.mailbox.compose(
+        "mbx_01krdgeqcxet5s7t44vh8rt9mg",
+        to=[{"address": "user@example.com"}],
+        subject="Hello",
+        text="Hi there",
+    )
+    print(msg.id, msg.thread_id)
+
+
+async def _ex_52() -> None:
+    mailbox = client.mailbox.create(display_name="Acme Support")
+    print(mailbox.id)
+
+
+async def _ex_53() -> None:
+    client.mailbox.delete("mbx_01krdgeqcxet5s7t44vh8rt9mg")
+
+
+async def _ex_54() -> None:
+    mailbox = client.mailbox.get("mbx_01krdgeqcxet5s7t44vh8rt9mg")
+    print(mailbox.address)
+
+
+async def _ex_55() -> None:
+    labels = client.mailbox.labels("mbx_01krdgeqcxet5s7t44vh8rt9mg")
+    for label in labels.data:
+        print(label.name)
+
+
+async def _ex_56() -> None:
+    for mailbox in client.mailbox.list():
+        print(mailbox.id, mailbox.address)
+
+
+async def _ex_57() -> None:
+    mailbox = client.mailbox.restore("mbx_01krdgeqcxet5s7t44vh8rt9mg")
+    print(mailbox.id)
+
+
+async def _ex_58() -> None:
+    mailbox = client.mailbox.resume("mbx_01krdgeqcxet5s7t44vh8rt9mg")
+    print(mailbox.id)
+
+
+async def _ex_59() -> None:
+    stats = client.mailbox.stats("mbx_01krdgeqcxet5s7t44vh8rt9mg")
+    print(stats.summary)
+
+
+async def _ex_60() -> None:
+    mailbox = client.mailbox.update("mbx_01krdgeqcxet5s7t44vh8rt9mg", display_name="Billing")
+    print(mailbox.display_name)
+
+
+async def _ex_61() -> None:
+    rule = client.mailbox_receive_rule.create(
+        "mbx_01krdgeqcxet5s7t44vh8rt9mg", action="block", entry="spam.example.com",
+    )
+    print(rule.id)
+
+
+async def _ex_62() -> None:
+    client.mailbox_receive_rule.delete(
+        "mbx_01krdgeqcxet5s7t44vh8rt9mg", "rrule_01krdgeqcxet5s7t44vh8rt9mg",
+    )
+
+
+async def _ex_63() -> None:
+    for rule in client.mailbox_receive_rule.list("mbx_01krdgeqcxet5s7t44vh8rt9mg"):
+        print(rule.id, rule.action)
+
+
+async def _ex_64() -> None:
+    client.mailbox_thread.delete("thr_01krdgeqcxet5s7t44vh8rt9mg")
+
+
+async def _ex_65() -> None:
+    thread = client.mailbox_thread.get("thr_01krdgeqcxet5s7t44vh8rt9mg")
+    print(thread.subject)
+
+
+async def _ex_66() -> None:
+    for thread in client.mailbox_thread.list():
+        print(thread.id, thread.subject)
+
+
+async def _ex_67() -> None:
+    thread = client.mailbox_thread.update(
+        "thr_01krdgeqcxet5s7t44vh8rt9mg",
+        labels={"add": ["archive"]},
+    )
+    print(thread.id)
+
+
+async def _ex_68() -> None:
+    result = client.mailbox_thread_message.attachments(
+        "thr_01krdgeqcxet5s7t44vh8rt9mg", "msg_01krdgeqcxet5s7t44vh8rt9mg",
+    )
+    for attachment in result.data:
+        print(attachment.filename, attachment.size)
+
+
+async def _ex_69() -> None:
+    body = client.mailbox_thread_message.body(
+        "thr_01krdgeqcxet5s7t44vh8rt9mg", "msg_01krdgeqcxet5s7t44vh8rt9mg",
+    )
+    print(body.html)
+
+
+async def _ex_70() -> None:
+    message = client.mailbox_thread_message.get(
+        "thr_01krdgeqcxet5s7t44vh8rt9mg", "msg_01krdgeqcxet5s7t44vh8rt9mg",
+    )
+    print(message.subject)
+
+
+async def _ex_71() -> None:
+    for message in client.mailbox_thread_message.list("thr_01krdgeqcxet5s7t44vh8rt9mg"):
+        print(message.id, message.subject)
+
+
+async def _ex_72() -> None:
+    reply = client.mailbox_thread_message.reply(
+        "thr_01krdgeqcxet5s7t44vh8rt9mg",
+        "msg_01krdgeqcxet5s7t44vh8rt9mg",
+        text="Thanks for reaching out!",
+    )
+    print(reply.id)
+
+
+async def _ex_73() -> None:
     for message in client.sms.list(direction="outbound"):
         print(message.id, message.status)
 
 
-async def _ex_52() -> None:
+async def _ex_74() -> None:
     msg = client.sms.send(
         to="+15551234567",
         text="Your verification code is 123456.",
@@ -350,54 +481,54 @@ async def _ex_52() -> None:
     print(msg.id, msg.status)
 
 
-async def _ex_53() -> None:
+async def _ex_75() -> None:
     client.sms.send(
         to="+15551234567",
         template="bird_otp_verification",
         parameters={"code": "123456"},
     )
 
 
-async def _ex_54() -> None:
+async def _ex_76() -> None:
     template = client.sms_templates.get("bird_otp_verification")
     print(template.body, template.variables)
 
 
-async def _ex_55() -> None:
+async def _ex_77() -> None:
     templates = client.sms_templates.list(scope="system")
     for template in templates.data:
         print(template.id, template.name)
 
 
-async def _ex_56() -> None:
+async def _ex_78() -> None:
     result = client.verify.verifications.check("123456", phone="+15551234567")
     print(result.success)
 
 
-async def _ex_57() -> None:
+async def _ex_79() -> None:
     verification = client.verify.verifications.create(phone="+15551234567")
     print(verification.id, verification.status)
 
 
-async def _ex_58() -> None:
+async def _ex_80() -> None:
     # Pass the RAW request body (bytes) and the request headers.
     event = client.webhooks.unwrap(request.body, request.headers)
     if event.root.type == "email.delivered":
         print(event.root.data.email_id)
 
 
-async def _ex_59() -> None:
+async def _ex_81() -> None:
     for message in client.whatsapp.list(status=["delivered"]):
         print(message.id, message.status)
 
 
-async def _ex_60() -> None:
+async def _ex_82() -> None:
     events = client.whatsapp.list_events("wam_01krdgeqcxet5s7t44vh8rt9mg")
     for event in events.data:
         print(event.type, event.occurred_at)
 
 
-async def _ex_61() -> None:
+async def _ex_83() -> None:
     msg = client.whatsapp.send(
         to="+31612345678",
         template="bird_otp",
@@ -407,7 +538,7 @@ async def _ex_61() -> None:
     print(msg.id, msg.status)
 
 
-async def _ex_62() -> None:
+async def _ex_84() -> None:
     templates = client.whatsapp_templates.list()
     for template in templates.data:
         print(template.name, template.status)

examples/reference/contacts.py

@@ -0,0 +1,31 @@
+"""Example source for the generated contacts methods.
+
+Each bird:snippet region is harvested for the docs site + README; the keys match
+the surface catalog (contacts.<leaf>). Hand-written and type-checked (pyright
+includes examples/); nothing regenerates over it. The override methods —
+contacts.update/batch/list — keep their examples inline in
+src/bird/resources/contacts.py, since nothing regenerates over a hand method.
+"""
+
+from bird import Bird
+
+client = Bird()
+
+
+def contacts_create() -> None:
+    contact = client.contacts.create(email="jane@acme.com", first_name="Jane")
+    print(contact.id, contact.email)
+
+
+def contacts_get() -> None:
+    contact = client.contacts.get("con_01krdgeqcxet5s7t44vh8rt9mg")
+    print(contact.email)
+
+
+def contacts_delete() -> None:
+    client.contacts.delete("con_01krdgeqcxet5s7t44vh8rt9mg")
+
+
+def contacts_list() -> None:
+    for contact in client.contacts.list(q="acme.com"):
+        print(contact.id, contact.email)

examples/reference/email.py

@@ -0,0 +1,115 @@
+"""Example source for the generated email.stats methods.
+
+Each bird:snippet region is harvested for the docs site + README; the keys
+match the surface catalog (email.stats.<leaf>). Hand-written and type-checked
+(pyright includes examples/); nothing regenerates over it.
+"""
+
+from bird import Bird
+
+client = Bird()
+
+def email_stats_summary() -> None:
+    summary = client.email.stats.summary(from_="2026-05-01", to="2026-05-25")
+    print(summary.sends_accepted, summary.delivery)
+
+
+def email_stats_daily() -> None:
+    stats = client.email.stats.daily(from_="2026-05-01", to="2026-05-25")
+    for point in stats.data:
+        print(point.bucket, point.sends_accepted)
+
+
+def email_stats_hourly() -> None:
+    stats = client.email.stats.hourly(
+        from_="2026-05-25T00:00:00Z",
+        to="2026-05-25T23:59:59Z",
+    )
+    for point in stats.data:
+        print(point.bucket, point.delivery)
+
+
+def email_stats_byTag() -> None:
+    stats = client.email.stats.by_tag(from_="2026-05-01", to="2026-05-25", sort="delivered")
+    for row in stats.data:
+        print(row)
+    print(stats.total)
+
+
+def email_stats_byCategory() -> None:
+    stats = client.email.stats.by_category(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_bySendingIp() -> None:
+    stats = client.email.stats.by_sending_ip(
+        from_="2026-05-01", to="2026-05-25", sort="bounces.block",
+    )
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_bySendingDomain() -> None:
+    stats = client.email.stats.by_sending_domain(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byRecipientDomain() -> None:
+    stats = client.email.stats.by_recipient_domain(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byMailboxProvider() -> None:
+    stats = client.email.stats.by_mailbox_provider(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byMailboxProviderRegion() -> None:
+    stats = client.email.stats.by_mailbox_provider_region(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byTemplate() -> None:
+    stats = client.email.stats.by_template(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byLocation() -> None:
+    stats = client.email.stats.by_location(
+        from_="2026-05-01", to="2026-05-25", group_by="country",
+    )
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byClient() -> None:
+    stats = client.email.stats.by_client(
+        from_="2026-05-01", to="2026-05-25", group_by="email_client",
+    )
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byBounceCode() -> None:
+    stats = client.email.stats.by_bounce_code(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byComplaintType() -> None:
+    stats = client.email.stats.by_complaint_type(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+
+
+def email_stats_byBroadcast() -> None:
+    stats = client.email.stats.by_broadcast(from_="2026-05-01", to="2026-05-25")
+    for row in stats.data:
+        print(row)
+

scripts/surface_ops.py

@@ -48,4 +48,20 @@
     "/v1/audiences/{audience_id}/contacts": {"get", "post"},
     "/v1/audiences/{audience_id}/contacts/remove": {"post"},
     "/v1/audiences/{audience_id}/contacts/{contact_id}": {"delete"},
+    "/v1/email/mailboxes": {"get", "post"},
+    "/v1/email/mailboxes/{mailbox_id}": {"delete", "get", "patch"},
+    "/v1/email/mailboxes/{mailbox_id}/restore": {"post"},
+    "/v1/email/mailboxes/{mailbox_id}/resume": {"post"},
+    "/v1/email/mailboxes/{mailbox_id}/stats": {"get"},
+    "/v1/email/mailboxes/{mailbox_id}/messages": {"post"},
+    "/v1/email/mailboxes/{mailbox_id}/labels": {"get"},
+    "/v1/email/mailboxes/{mailbox_id}/receive-rules": {"get", "post"},
+    "/v1/email/mailboxes/{mailbox_id}/receive-rules/{rule_id}": {"delete"},
+    "/v1/email/threads": {"get"},
+    "/v1/email/threads/{thread_id}": {"delete", "get", "patch"},
+    "/v1/email/threads/{thread_id}/messages": {"get"},
+    "/v1/email/threads/{thread_id}/messages/{message_id}": {"get"},
+    "/v1/email/threads/{thread_id}/messages/{message_id}/body": {"get"},
+    "/v1/email/threads/{thread_id}/messages/{message_id}/reply": {"post"},
+    "/v1/email/threads/{thread_id}/messages/{message_id}/attachments": {"get"},
 }