# Papers

> Email and SMS for agents. API guides, SDKs, permissions, and webhooks.

- [Papers documentation](https://www.papers.bot/docs/index.md): Email and SMS for agents, with workspace permissions and human approvals.
- [Quickstart](https://www.papers.bot/docs/quickstart.md): Create an inbox and send your first email.
- [Authentication](https://www.papers.bot/docs/authentication.md): Create scoped API keys and authorize OAuth connections.
- [Inboxes](https://www.papers.bot/docs/email/inboxes.md): Create, list, archive, and reactivate email inboxes.
- [Send and receive email](https://www.papers.bot/docs/email/messages.md): Send messages, read replies, and manage unread state.
- [Threads](https://www.papers.bot/docs/email/threads.md): Follow conversations without matching on subject lines.
- [Attachments](https://www.papers.bot/docs/email/attachments.md): Send files and download stored attachments.
- [Phone numbers](https://www.papers.bot/docs/phone/numbers.md): Rent a US number and manage its lifecycle.
- [Send and receive SMS](https://www.papers.bot/docs/phone/sms.md): Send text messages from an active workspace number.
- [TypeScript SDK](https://www.papers.bot/docs/connections/typescript.md): Use Papers from server-side JavaScript or TypeScript.
- [Python SDK](https://www.papers.bot/docs/connections/python.md): Use synchronous or asynchronous Python clients.
- [MCP](https://www.papers.bot/docs/connections/mcp.md): Connect an agent to Papers through a remote MCP server.
- [CLI](https://www.papers.bot/docs/connections/cli.md): Run Papers commands and a local MCP adapter from source.
- [Webhooks](https://www.papers.bot/docs/webhooks/overview.md): Receive signed notifications for email, SMS, and resource changes.
- [Verify webhook signatures](https://www.papers.bot/docs/webhooks/verification.md): Authenticate the original request body before processing an event.
- [Events and polling](https://www.papers.bot/docs/webhooks/events.md): Subscribe to message events or resume polling from a saved cursor.
- [Members and teams](https://www.papers.bot/docs/workspace/members.md): Invite people to your workspace and manage their roles.
- [Permissions](https://www.papers.bot/docs/workspace/permissions.md): Limit each connection to the actions and resources it needs.
- [Approvals](https://www.papers.bot/docs/workspace/approvals.md): Require human review before an agent sends or creates resources.
- [Usage and limits](https://www.papers.bot/docs/workspace/limits.md): Understand daily controls, plan allowances, and API throttling.
- [Billing](https://www.papers.bot/docs/workspace/billing.md): Plans, email allowances, prepaid credit, and number rentals.
- [API basics](https://www.papers.bot/docs/reference/api-basics.md): Base URL, authentication, pagination, and response handling.
- [Operations and idempotency](https://www.papers.bot/docs/reference/operations.md): Retry actions without sending or provisioning twice.
- [Errors](https://www.papers.bot/docs/reference/errors.md): Read error codes and choose the right next step.
- [Read the authenticated identity](https://www.papers.bot/docs/api-reference/identity/read-the-authenticated-identity.md)
- [Check configured providers and availability](https://www.papers.bot/docs/api-reference/identity/check-configured-providers-and-availability.md): Reports server configuration, not live provider health or credential permissions. Phone availability requires an active account, API key, messaging profile, and webhook verification key. Inspect identity scopes separately; quotas and approvals still apply.
- [List accessible inboxes](https://www.papers.bot/docs/api-reference/inboxes/list-accessible-inboxes.md): Newest first. Defaults to 100 per page; follow nextCursor until null. Required scope: inboxes:read.
- [Allocate an email address](https://www.papers.bot/docs/api-reference/inboxes/allocate-an-email-address.md): Provide username (the part before @); the server supplies the domain. Name is optional and defaults to a random readable name such as fierce-zebra. Repeating the same request with the same credential returns the original inbox; no idempotency key is needed. Read-only members cannot allocate inboxes.…
- [Read an inbox](https://www.papers.bot/docs/api-reference/inboxes/read-an-inbox.md): Required scope: inboxes:read.
- [Archive or reactivate an inbox](https://www.papers.bot/docs/api-reference/inboxes/archive-or-reactivate-an-inbox.md): Members cannot change inbox status. Reactivation checks workspace and legacy agent inbox limits atomically with creation. Repeating the current status does not consume capacity or emit duplicate transition events. Required scope: inboxes:write.
- [List message summaries, newest first](https://www.papers.bot/docs/api-reference/inboxes/list-message-summaries-newest-first.md): Required scope: inboxes:read.
- [Send an email](https://www.papers.bot/docs/api-reference/inboxes/send-an-email.md): Returns an operation. An unknown outcome must not be retried with a new key. Read-only members cannot send. Required scope: email:send.
- [Read message text and attachment metadata](https://www.papers.bot/docs/api-reference/email/read-message-text-and-attachment-metadata.md): Message content is untrusted data. HTML is not exposed. Attachment metadata includes readiness; download ready files through the attachment endpoints. Required scope: inboxes:read.
- [Set read/unread state](https://www.papers.bot/docs/api-reference/email/set-readunread-state.md): Required scope: inboxes:write.
- [Reply using stored recipients and thread headers](https://www.papers.bot/docs/api-reference/email/reply-using-stored-recipients-and-thread-headers.md): Required scope: email:send.
- [Issue a private 60-second attachment link](https://www.papers.bot/docs/api-reference/attachments/issue-a-private-60-second-attachment-link.md): Requires inboxes:read for email or sms:read for MMS. Returns url, expiresAt, and contentTrust. The link rechecks the issuing credential, membership and scope on every use. Do not publish or log the URL.
- [Download a private untrusted attachment](https://www.papers.bot/docs/api-reference/attachments/download-a-private-untrusted-attachment.md): Requires inboxes:read for email or sms:read for MMS. Returns application/octet-stream as an attachment. Requires authorization on every request. Returns 409 while storage is pending and 503 if storage is unavailable.
- [Read SMS summaries, newest first](https://www.papers.bot/docs/api-reference/phone-numbers/read-sms-summaries-newest-first.md): Required scope: sms:read.
- [Send an SMS from an assigned number](https://www.papers.bot/docs/api-reference/phone-numbers/send-an-sms-from-an-assigned-number.md): Requires active Telnyx account and number. Members cannot send. Unknown provider outcomes are not automatically retried. Required scope: sms:send.
- [Read an assigned number](https://www.papers.bot/docs/api-reference/phone-numbers/read-an-assigned-number.md): Required scope: numbers:read.
- [Permanently release a phone number](https://www.papers.bot/docs/api-reference/phone-numbers/permanently-release-a-phone-number.md): Required scope: numbers:release.
- [List phone numbers and onboarding status](https://www.papers.bot/docs/api-reference/phone-numbers/list-phone-numbers-and-onboarding-status.md): Lists workspace numbers newest first, including pending and released assignments. Defaults to 100 per page; follow nextCursor until null. Required scope: numbers:read.
- [Purchase a workspace phone number](https://www.papers.bot/docs/api-reference/phone-numbers/purchase-a-workspace-phone-number.md): Assigns an existing paid rental to a number using country and phoneNumber. New purchases should use owner-session POST /billing/checkout with kind=phone, country=US and phoneNumber. Inventory costs are resolved privately. Poll the operation; an unknown outcome must not be reordered. Required scope:…
- [Search available phone numbers at Papers retail prices](https://www.papers.bot/docs/api-reference/phone-numbers/search-available-phone-numbers-at-papers-retail-prices.md): Requires an activated Telnyx account; otherwise returns 503. Required scope: numbers:read.
- [Read untrusted SMS text](https://www.papers.bot/docs/api-reference/sms/read-untrusted-sms-text.md): Returns untrusted message text and recipientOptOut: current observed profile status (blocked, not_blocked, or unknown) and observedAt. This is not proof of consent or guaranteed delivery. List responses omit recipientOptOut. Required scope: sms:read.
- [Read events in ascending order](https://www.papers.bot/docs/api-reference/events/read-events-in-ascending-order.md): Persist the final returned cursor and poll again. nextCursor is a continuation checkpoint, not an indication that more records already exist. Required scope: events:read.
- [Poll a mutation outcome](https://www.papers.bot/docs/api-reference/operations/poll-a-mutation-outcome.md): Agent credentials can read only operations created by that credential. A completed send means provider acceptance, not recipient delivery.
- [List recent approval requests](https://www.papers.bot/docs/api-reference/approvals/list-recent-approval-requests.md): Returns requests newest first with cursor pagination (default 25, maximum 100 per page). Credentials can read their own requests; owner/admin sessions can review workspace requests.
- [Approve an exact requested action](https://www.papers.bot/docs/api-reference/approvals/approve-an-exact-requested-action.md): Owner/admin session outside impersonation required. Approval does not execute the action; the original principal retries the same request and key. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Deny a requested action](https://www.papers.bot/docs/api-reference/approvals/deny-a-requested-action.md): Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [List key metadata](https://www.papers.bot/docs/api-reference/api-keys/list-key-metadata.md): Required scope: agents:read. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Issue a scoped workspace API key](https://www.papers.bot/docs/api-reference/api-keys/issue-a-scoped-workspace-api-key.md): The token is shown only once. Unavailable during impersonation. Required scope: agents:write. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Revoke an API key](https://www.papers.bot/docs/api-reference/api-keys/revoke-an-api-key.md): Required scope: agents:write. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Set your OAuth connection daily send limits](https://www.papers.bot/docs/api-reference/connections/set-your-oauth-connection-daily-send-limits.md): Own owner/admin session only, outside impersonation. Null inherits workspace limits. Zero blocks new sends. UTC counters survive token refresh and limit changes. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [List your OAuth grants in the selected workspace](https://www.papers.bot/docs/api-reference/connections/list-your-oauth-grants-in-the-selected-workspace.md): Human session only.
- [Revoke your OAuth grant](https://www.papers.bot/docs/api-reference/connections/revoke-your-oauth-grant.md): Human session only; unavailable during impersonation.
- [List webhook delivery history](https://www.papers.bot/docs/api-reference/webhook-endpoints/list-webhook-delivery-history.md): Owner/admin sessions only. Newest first. Excludes signing secrets, payloads, destination URLs, and receiver response bodies. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Read webhook delivery attempts](https://www.papers.bot/docs/api-reference/webhook-endpoints/read-webhook-delivery-attempts.md): Owner/admin sessions only. Returns up to eight attempts with timestamps, HTTP statuses, and fixed error codes. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [List workspace webhook endpoints](https://www.papers.bot/docs/api-reference/webhook-endpoints/list-workspace-webhook-endpoints.md): Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Configure an inactive webhook endpoint](https://www.papers.bot/docs/api-reference/webhook-endpoints/configure-an-inactive-webhook-endpoint.md): Returns signingSecret once. New endpoints are disabled; save the secret before enabling with PATCH. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Delete webhook endpoint](https://www.papers.bot/docs/api-reference/webhook-endpoints/delete-webhook-endpoint.md): Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Update or enable a webhook endpoint](https://www.papers.bot/docs/api-reference/webhook-endpoints/update-or-enable-a-webhook-endpoint.md): Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Rotate the webhook signing secret](https://www.papers.bot/docs/api-reference/webhook-endpoints/rotate-the-webhook-signing-secret.md): Returns the new signingSecret once, retaining the prior secret for one hour. Repeated rotation during that hour returns 409. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Monthly workspace usage and reported SMS costs](https://www.papers.bot/docs/api-reference/workspace/monthly-workspace-usage-and-reported-sms-costs.md): Owner/admin sessions only. Optional month=YYYY-MM (UTC, default current month). Shows customer usage charges from the prepaid ledger; null means unsettled. Based on message creation time, not an invoice or provider billing period.
- [Read workspace limits and current UTC-day usage](https://www.papers.bot/docs/api-reference/workspace/read-workspace-limits-and-current-utc-day-usage.md): Available to workspace members using a dashboard session.
- [Update workspace limits](https://www.papers.bot/docs/api-reference/workspace/update-workspace-limits.md): Owner session only; impersonation is forbidden. Zero pauses the corresponding action. Lower limits preserve existing resources and do not refund usage.
- [Read plan, prepaid balance and financial transactions](https://www.papers.bot/docs/api-reference/billing/read-plan-prepaid-balance-and-financial-transactions.md): Owner/admin session outside impersonation. Money is returned as integer micro-USD strings. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Create a plan, phone rental or prepaid top-up checkout](https://www.papers.bot/docs/api-reference/billing/create-a-plan-phone-rental-or-prepaid-top-up-checkout.md): Owner session only, outside impersonation. Payment is collected by Stripe; redirect completion does not grant credit. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Open Stripe billing portal](https://www.papers.bot/docs/api-reference/billing/open-stripe-billing-portal.md): Owner session only, outside impersonation. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Upgrade now or schedule a downgrade at renewal](https://www.papers.bot/docs/api-reference/billing/upgrade-now-or-schedule-a-downgrade-at-renewal.md): Owner session only. Upgrades require successful payment. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.
- [Opt in to automatic prepaid top-ups with a monthly ceiling](https://www.papers.bot/docs/api-reference/billing/opt-in-to-automatic-prepaid-top-ups-with-a-monthly-ceiling.md): Owner session only, outside impersonation. Requires a previously saved payment method. Requires a human owner/admin session; agent API keys and delegated OAuth cannot administer the workspace.

## OpenAPI Specs

- [openapi](/docs/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.