nextmail 0.0.1__tar.gz

nextmail-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

nextmail-0.0.1/CHANGELOG.md

@@ -0,0 +1,283 @@
+# Changelog
+
+## 0.0.1
+
+The first release of the Python package. It has a method for every one of the 746 methods of the
+TypeScript SDK, in 53 namespaces, each under its TypeScript name in snake_case, and a parity check
+in the package's own build proves that every one sends the same request as its TypeScript twin.
+
+- Two clients with the same methods and arguments: `Nextmail`, which blocks, and `AsyncNextmail`,
+  which is awaited and runs on asyncio and on trio. Each has an attribute for every namespace, from
+  `emails`, `threads` and `templates` to `automations`, `bookings` and `connected_mailboxes`.
+- A request body is a dict whose keys keep the API's camelCase names, the options of a call are
+  snake_case keyword arguments such as `idempotency_key=` and `limit=`, and a response comes back as
+  a dict. Every body, result and webhook payload has a `TypedDict` in `nextmail.types`, so a type
+  checker catches a misspelt key.
+- A client takes an API key or an OAuth access token, or reads `NEXTMAIL_API_KEY`,
+  `NEXTMAIL_ACCESS_TOKEN` and `NEXTMAIL_BASE_URL`. `access_token=` also takes a function that
+  returns the token, called before every request, which may be async on `AsyncNextmail`.
+  `base_url`, `timeout`, `max_retries`, `headers`, `user_agent` and `http_client`, your own `httpx`
+  client, set the rest. Every method also takes `timeout=` for one call, and `api_key=`, or
+  `inbox_token=` on `temp_mail`, to act with another credential.
+- Every workspace is the same kind, the one that holds the free address included. That address
+  sends only the mail a person writes in the app, so a send from it with an API key or an access
+  token is refused with `from_address_forbidden`.
+- `from nextmail import nextmail` is a ready-made client, built from the environment the first time
+  it is touched, and `init(...)` configures it once at startup. `create_temp_mail()` and
+  `create_async_temp_mail()` open disposable inboxes with no credential.
+- Every paginated resource has `list` for one page, `list_all` for every item as a list, and
+  `iterate`, which yields each item and fetches the next page only when it gets there.
+- An API refusal raises `NextmailApiError`, with `status`, `type`, `code`, `param`, `doc_url`,
+  `request_id`, `retry_after_seconds` and `fields`, and checks such as `is_validation`,
+  `is_not_found`, `is_rate_limited`, `is_step_up_required` and `is_retryable`. No response at all
+  raises `NextmailNetworkError`, with `is_timeout` when the deadline passed. Both derive from
+  `NextmailError`, and a mistake in the call itself raises `ValueError` before anything is sent.
+- Reads, sends and every write that is safe to repeat are retried on 408, 500, 502, 503 and 504 with
+  backoff, and on a 429 only when its `Retry-After` is a minute or less. A send carries an
+  idempotency key that its retries reuse, so a retry never sends a second message. `timeout` bounds
+  a whole attempt, the response body included, and uploads wait at least ten minutes.
+- `verify_webhook_signature` checks a delivery in constant time, refuses one more than five minutes
+  old and returns the parsed event, or raises `WebhookVerificationError`.
+- The helpers of the TypeScript SDK are here too, such as `to_base64` and `resolve_language`, and
+  every value set it exports is a constant in `nextmail.constants`, such as `WEBHOOK_EVENTS` and
+  `API_SCOPES`.
+- `client.raw.request()` reaches any endpoint with the client's credential, base URL, timeout and
+  retries, and a credential is never sent over plain HTTP, except to a server on this machine.
+- When a newer version is on PyPI, the client says so once, on a terminal only.
+  `disable_update_notice=True` or `NEXTMAIL_DISABLE_UPDATE_NOTICE=1` turns that off.
+- It needs Python 3.10 or newer and depends only on `httpx`, `anyio` and `typing-extensions`.
+- API keys begin `nm_live_` or `nm_test_`, and temporary inbox tokens `nm_inbox_`. The client
+  refuses a key of any other shape.
+- Images up to 100 MB go in on `account.set_photo`, `contacts.set_photo`,
+  `domains.set_address_photo`, `bookings.upload_background`, `branding.upload_image` and
+  `templates.upload_image`. Each also takes `crop=`, the part of the image to keep as an
+  `ImageCrop` of fractions, and waits as long as `files.upload` does.
+- `emails.list_events_by_message_id`, `list_all_events_by_message_id` and
+  `iterate_events_by_message_id` read the event trail of a sent email found by the Message-ID header
+  it went out with, for a caller that holds that header and not the `msg_` id, such as a reply or a
+  bounce report that quotes it. They take the Message-ID as their first argument, sent as
+  `messageId`, with `limit=`, `cursor=` and `address=` as on `list_events`. A Message-ID that no
+  message the key reaches went out with is a 404.
+- `provider_imports.list`, `list_all` and `iterate` take `source=` (one of
+  `PROVIDER_IMPORT_PROVIDERS`, typed as `ProviderImportProvider`), `status=` (one of
+  `IMPORT_HISTORY_STATUSES`, typed as `ImportHistoryStatus`) and `search=`, up to 320 characters,
+  the filters `imports.list` takes, sent with every page. An import from a provider never pauses, so
+  `status='paused'` answers an empty page.
+- `emails.list_events`, `list_all_events` and `iterate_events` take `message_id=`, 1 to 998
+  characters, sent as `messageId`: the trail answers only when the send went out with that
+  Message-ID header, with or without its angle brackets, and is a 404 otherwise. The send id is
+  still required.
+- `files.create_link` takes `reuse=`: `True` hands back the working public link the file already
+  has, with its own domain and download count, instead of making another, and a file with none gets
+  a new one. A link handed back answers 200 and a new one 201.
+- `keys.create`, `update` and `delete`, `keys.rotate` for any key but the caller, and
+  `workspaces.offer_ownership`, `withdraw_ownership_offer`, `account.accept_ownership_offer` and
+  `decline_ownership_offer` refuse an API key with 403 `console_only`, `ERROR_CODES.CONSOLE_ONLY` in
+  `nextmail.constants`. The console confirms these changes with a verification code, which a key
+  cannot give, so they are made there. A key still rotates its own secret with `keys.rotate` or
+  `me.rotate`, and revokes keys with `keys.revoke`.
+- `app_host.get`, `set` and `verify` return `sender`, typed as `AppHostSender` in `nextmail.types`:
+  where the emails sent to the people of the workspace come from, a dict with `address`, `domain`
+  and `waitingOn`. `waitingOn` is `logo` or `signing`, one of `APP_HOST_SENDER_WAITS` and typed as
+  `AppHostSenderWait`, until they come from `noreply@` the domain of the live web app address, then
+  `None`. `sender` is `None` on the free plan and until an address on a verified domain of the
+  workspace is live.
+- `addresses.list`, `list_all` and `iterate` give each address a `role`, one of `ADDRESS_ROLES` and
+  typed as `AddressRole`: `owner` on every address for an API key, and `member` or `viewer` for an
+  app a member connected. A key narrowed to particular addresses or domains lists only the addresses
+  and domains it covers, and the free address of the person the key acts for is listed, with `role`
+  set to `owner`, by a key of the workspace it belongs to.
+- `chats.send_message` says something in a chat with the assistant, or starts one, and returns the
+  turn once the assistant has replied, typed as `ChatTurnResource` in `nextmail.types`: its
+  `status`, one of `CHAT_TURN_STATUSES`, the `messages` it added, `stopReason` and the
+  `pendingToolCalls` that wait for an answer. `chats.approve_tool_call` runs one, with `args` laid
+  over the ones the assistant chose, `chats.deny_tool_call` refuses one, and `chats.stop_turn`
+  stops a turn and answers `stopped` or `idle`, from `CHAT_STOP_STATUSES`. The three calls that
+  wait for the assistant wait up to 300 seconds, or the client's `timeout` when that is longer,
+  unless `timeout=` says otherwise, and `timeout=0` waits as long as it takes. None of the four is
+  retried. The refusals are 409 `chat_busy` and `approval_pending`, 403 `tool_not_offered` and 503
+  `assistant_unavailable`.
+- `chats.list_messages`, `list_all_messages` and `iterate_messages` read the messages of a chat,
+  from the first or, with `order='desc'`, from the newest, each with its `text` and its `parts`,
+  typed as `ChatMessageResource`. `CHAT_MESSAGE_ORDERS`, `CHAT_MESSAGE_ROLES`,
+  `CHAT_MESSAGE_PART_TYPES`, `CHAT_TOOL_CALL_STATUSES` and `CHAT_STOP_REASONS` hold the values.
+- `members.get_directory_sync`, `connect_directory_sync` and `disconnect_directory_sync` read, turn
+  on and turn off directory sync (SCIM), through which a company directory adds people and takes
+  them out again. `connect_directory_sync` returns the token once. `members.list_directory_people`
+  pages through the people it synced with `start_index=` and `count=`, each in one of
+  `DIRECTORY_PERSON_STATES`, and `members.set_directory_default_role` and `set_directory_group_role`
+  choose the roles it gives. Only the owner or a role holding `workspace:manage` reaches them, and
+  every change asks an OAuth access token for a verification code.
+- `security.get_policy` and `security.update_policy` read and set whether everyone in the workspace
+  has to sign in with two-factor authentication, typed as `SecurityPolicyResource`. `get_policy`
+  needs no scope and also says whether the person behind the client meets the rule, and
+  `update_policy` needs `members:write` and a verification code.
+- `workspaces.get_ownership_offer`, `offer_ownership` and `withdraw_ownership_offer` offer the
+  workspace to one of its members, and `account.list_ownership_offers`, `accept_ownership_offer` and
+  `decline_ownership_offer` answer an offer. Offering and accepting ask for a verification code.
+- `account.set_name` changes the name of the person. `account.list_push_devices`,
+  `remove_push_device` and `send_test_push` read and manage the phones that get their
+  notifications, with `platform` from `PUSH_PLATFORMS`, and
+  `account.end_connected_app_elevation` makes a connected app ask for verification codes again.
+- `threads.set_replying` and `clear_replying` show the team that you are writing a reply.
+  `threads.list_tracking` reads how the mail sent in a thread was read, `threads.get_delivery`
+  whether it arrived, typed as `ThreadDeliveryResource`, and `threads.list_file_links`,
+  `list_all_file_links` and `iterate_file_links` the download links one message carried, with
+  `include_revoked=`. `threads.counts` takes `hide_labelled=`.
+- `senders.get_avatar` returns the picture found for a sender as `bytes`, and `senders.get` and
+  `research` report `avatarUrl` and `avatarKind`, one of `SENDER_AVATAR_KINDS`.
+- `dns_connections.start` returns the link that connects a Cloudflare account in a browser,
+  `domains.start_gravatar_publish` the link that publishes the photo of an address to Gravatar,
+  and `domains.create_mail_app_profile_link` a one-time link that sets an address up on an Apple
+  device.
+- `emails.send` and `emails.send_batch` take `isForward` and `originalMessage`, the email being
+  forwarded or answered, quoted below the body, and `encryption`, typed as `SealedMessageInput`,
+  for a message you sealed yourself with OpenPGP. `emails.translate` takes `skipQuoted` and
+  reports `quotedHistoryKept`.
+- `emails.get_tracking`, `list_events`, `list_all_events` and `iterate_events` take `address=`, and
+  so do `tracking.list_opens`, `list_clicks` and their walks. `tracking.list`, `list_all` and
+  `iterate` take `offset_minutes=`, and `tracking.get_stats` reports `downloads`, typed as
+  `TrackingDownloads`.
+- `contacts.list`, `list_all` and `iterate` take `audience_id=`, and `contacts.activity` takes
+  `from_=` and `to=`. `audiences.list_contacts` and its walks take `inactive_days=`.
+  `audiences.growth`, `bookings.analytics` and `forms.analytics` take `since=` and `until=`, and
+  `broadcasts.analytics` and `broadcasts.stats` take `since=`. `imports.list` and its walks take
+  `source=`, `status=`, one of `IMPORT_HISTORY_STATUSES`, and `search=`, `rules.list_runs` and its
+  walks take `rule_ids=`, and `signatures.list` and its walks take `from_=`.
+- `audiences.add_contact` and `contacts.set_audiences` take `createContact`, which saves an address
+  that is not a contact yet first and needs `contacts:write`. Through an app a member connected,
+  an address another member saved is a 409 `contact_exists` there and on `contacts.save`.
+- `templates.update` and `templates.replace_content` take `expectedUpdatedAt`, and
+  `templates.publish` takes `expected_updated_at=`: the `updatedAt` every template version reports.
+  A draft saved again in between is a 409 `version_conflict`.
+- `drafts.create` and `drafts.update` take `attachments`: inline files of up to 5 MB, with
+  `content` as `bytes` or base64, or stored files by `fileId`. Every draft attachment reports
+  `fileId`.
+- An attachment given as `{'url': ...}` is sent as it is, with its `filename` and `contentType` when
+  they are set.
+- Scopes: `addresses.list` and its walks need `emails:read` or `emails:send`,
+  `audiences.list_contacts` and its walks need `contacts:read` too, `emails.compose`, `rewrite`,
+  `suggest_subject` and `translate` take `drafts:write` in place of `emails:send`,
+  `domains.get_mail_app_settings` and `list_app_passwords` need `threads:read`, and
+  `domains.update_mail_app_settings` needs `threads:read` as well as `domains:write`.
+  `domains.create_address` asks an OAuth access token for a verification code when it chooses where
+  the mail goes or deletion on expiry.
+- `domains.create_address` and `domains.update_address` take `expiresAt` and `onExpiry`, one of
+  `ADDRESS_EXPIRY_ACTIONS`, and every address reports them with `expiredAt`. From its `expiresAt` an
+  address takes no mail and sends none, a send from it is refused with 403 `address_expired`, and
+  within a minute it is switched off, or deleted with the conversations delivered to it when
+  `onExpiry` is `delete`. A later `expiresAt`, `None` or `enabled` set to `True` turns a stopped
+  address back on. `WEBHOOK_EVENTS.ADDRESS_EXPIRED` is the event `address.expired`, typed as
+  `AddressExpiredEventData` in `nextmail.types`.
+- `DOMAIN_ADDRESS_DESTINATIONS` includes `WEBHOOK` and `GROUP`. The same two methods take
+  `webhookId` for a webhook destination, `tapWebhookIds` to copy every message to up to 5 endpoints,
+  and `groupPosting`, one of `ADDRESS_GROUP_POSTING_POLICIES`, and `groupKeepCopy` for a group, and
+  every address reports them. The refusals are `webhook_not_found` and `too_many_taps`.
+- `WEBHOOK_EVENTS.EMAIL_ROUTED` is the event `email.routed`, typed as `EmailRoutedEventData`: a
+  message that arrived at an address whose destination is `webhook`, or that a route of its domain
+  sent to a webhook, was kept for 30 days instead of being filed. It goes only to the endpoint the
+  address or route names and to the taps of the address, and always carries `content` and `raw`.
+  `routedBy`, whose `kind` is one of `WEBHOOK_ROUTED_SOURCES`, says which sent it, `recipient`
+  keeps the plus tag and `verdicts` are what the receiving server found. An `email.received`
+  event carries `tap`, `True` when an endpoint gets the message as a tap of the address rather
+  than through its subscription.
+- `domains.list_routes`, `list_all_routes` and `iterate_routes` read the pattern routes of a
+  domain in the order they are tried, typed as `AddressRouteResource` in `nextmail.types`.
+  `domains.create_route`, `get_route`, `update_route` and `delete_route` manage them: a route
+  catches mail to addresses nobody created whose local part matches its `pattern`, such as
+  `support-*`, and delivers it to an address, forwards it once the destination confirms, posts it
+  to a webhook as `email.routed` or reads it on another domain, the actions
+  `ADDRESS_ROUTE_ACTIONS` lists. `active` and `inactiveReason`, one of
+  `ADDRESS_ROUTE_INACTIVE_REASONS`, say whether a route takes mail now. A domain holds at most 100
+  routes, and the refusals are `invalid_route_pattern`, `route_pattern_taken`,
+  `route_target_not_found` and `route_limit_reached`. `domains.test_route` answers which step
+  decides mail to an address without sending anything, one of `ADDRESS_ROUTE_TEST_STEPS`, with the
+  route that decided and where the mail would go, typed as `AddressRouteTestResource`.
+- `domains.list_group_members`, `list_all_group_members` and `iterate_group_members` read the
+  group members of a group address, typed as `GroupMemberResource`, and
+  `domains.add_group_members` and `remove_group_member` change them. A group member is an address
+  of the workspace or an address at another provider, which confirms by email first, the kinds
+  `GROUP_MEMBER_KINDS` lists. A group holds at most 1,000 group members and groups nest at most 3
+  deep, and the refusals are `not_a_group`, `group_member_limit`, `group_member_not_found` and
+  `group_nesting_too_deep`.
+- `domains.update` takes `aliasOf`, which makes the domain an alias of another domain of the
+  workspace, and every domain reports `aliasOf` and `aliases`, typed as `DomainAlias`. The
+  refusals are `alias_not_allowed`, `alias_chain` and `alias_has_addresses`, and creating an
+  address on an alias is refused with `alias_has_addresses`.
+- `domains.update_address_limits` takes `receiving['storageBytes']`, a storage quota for one
+  address from 1 MiB to 1 TiB, and the limits report it. A message that would take the address
+  past its quota gets a permanent bounce (5.2.2), and deleting mail for good makes room again.
+  `domains.get_address_limits` reports what the address keeps in `usage['storage']`, with `bytes`
+  and `messages`, typed as `AddressStorageUsage` in `nextmail.types`. Mail stored before storage
+  counting began and mail routed to a webhook are not counted.
+- `webhooks.list_dead_letters`, `list_all_dead_letters` and `iterate_dead_letters` read the events
+  an endpoint gave up on: each event whose last automatic attempt failed, with how many times it
+  was tried, the last answer and that attempt, typed as `WebhookDeadLetterResource`. `status=`
+  reads the `open` ones by default, or `replayed`, `discarded` or `all` from
+  `WEBHOOK_DEAD_LETTER_FILTERS`, and `WEBHOOK_DEAD_LETTER_STATUSES` holds the statuses a dead
+  letter can have. A dead letter is kept 30 days.
+- `webhooks.replay_dead_letters` sends up to 100 open dead letters again in one call, the ones
+  named in `body['ids']` or the oldest, and returns an `outcome` for each from
+  `WEBHOOK_DEAD_LETTER_REPLAY_OUTCOMES`. A delivered one is closed as `replayed`.
+  `webhooks.discard_dead_letter` closes one without sending it, and one already replayed is 409
+  `dead_letter_resolved`.
+- `webhooks.create` and `webhooks.update` take `retryPolicy` from `WEBHOOK_RETRY_POLICIES`:
+  `standard` tries a failed delivery up to 8 times over about 27 and a half hours, and `extended` up
+  to 16 times over about 3 days. They also take `includeRaw`, which needs `threads:read`, and every
+  endpoint reports both.
+- `threads.get_raw_message` returns the source of one message as `message/rfc822` `bytes`, ready
+  to save as an `.eml` file. It is the message byte for byte as it arrived when the address had
+  `keepOriginal` on, and otherwise a source rebuilt from the stored message, the same bytes the
+  IMAP server gives a mail app. The `X-Message-Source` response header says which, one of
+  `RAW_MESSAGE_SOURCES`.
+- `domains.create_address` and `domains.update_address` take `keepOriginal`, and every address
+  reports it. While it is on, each message the address receives is also kept byte for byte as it
+  arrived, and it is deleted with its message.
+- An `email.received` event to an endpoint with `includeRaw` on carries `data['raw']`, typed as
+  `WebhookMessageRaw`: a link that downloads the message source for an hour, its `size` and its
+  `source`, `original` or `rebuilt`.
+- `domains.get_address_limits` and `domains.update_address_limits` read and change what one address
+  may send and receive: a hold that pauses or disables sending or receiving, caps per hour, per 24
+  hours and per month on messages and recipients, recipients per message, and lists of allowed and
+  blocked recipients and allowed senders, with the usage so far. `ADDRESS_HOLDS` lists the holds.
+- `domains.get` and `domains.update` give each DNS record `found`, what public DNS answers at that
+  name now, and `problem`, a dict with a `code` from `DOMAIN_RECORD_PROBLEMS` and a `message` to
+  show a person.
+- `domains.update` takes `autodiscovery` in the patch: `True` offers the SRV and TXT records that
+  let mail, calendar and contacts apps find the servers from an address on the domain alone, listed
+  in `autodiscoveryRecords`.
+- `webhooks.create` and `webhooks.update` take `includeContent`, which puts the message into every
+  `email.received` event as `data['content']`: the text, the HTML up to 512 KiB and each attachment
+  with a link that downloads it for an hour. Turning it on needs `threads:read`.
+- A connected mailbox can be the sender of `emails.send` with an API key, of broadcasts,
+  automations and sign-up forms, and a key or an app can send from the free address of the person
+  it acts for. Only that person may send as a free address.
+- `threads.counts()` leaves labelled mail out of `team.assigned` and `team.unassigned`, as the inbox
+  does, unless the person has chosen to show labelled mail in the inbox.
+- `domains`, `members`, `keys`, `webhooks` and `rules` take `q=` on `list`, `list_all` and
+  `iterate`, and so does `connected_mailboxes.list`. It searches every field a person reads on the
+  row: names, addresses, ids, scopes, events, condition values. Every word has to appear, ignoring
+  case and accents, and close spellings count when nothing matches exactly.
+- `rules.stats()` reads how the rules did inside a window: messages matched and failed, a series of
+  buckets, the matches of each rule, the actions taken, the failures and the senders matched most.
+  `rule_ids=` counts some rules only, and the result is typed as `RuleStatsResource` in
+  `nextmail.types`.
+- `billing.get()` reports `usage.addressChecks`: the deep address checks used this calendar month,
+  what the plan includes and when they start again, beside `payAsYouGo.coversAddressChecks` and
+  `extraAddressChecks`. `billing.list_plans()` gives each plan's `monthlyAddressChecks`, and
+  `billing.get_pay_as_you_go()` adds `prices.addressChecks` and `period.addressChecks`, all typed in
+  `nextmail.types`.
+- `tools.check_address` and `tools.check_addresses` with `deep=True` first use the deep checks the
+  plan includes each month (10 on Free, 100 on Starter, 500 on Business, 1,000 on Enterprise), then
+  pay as you go at $1.50 per 100 addresses.
+- An automation branch can check the contact's address: `{'kind': 'address_check', 'mailbox': ...,
+  'accept': ...}`, with `accept` from `nextmail.AUTOMATION_ADDRESS_ACCEPTS` and the condition typed as
+  `AutomationAddressCondition` in `nextmail.types`.
+- A send leaves out an address whose domain takes no mail, and one the check on sending finds has no
+  mailbox. Each shows as `suppressed`, with an `email.suppressed` webhook that names the reason,
+  never as a bounce.
+- Forms check the address of every sign-up: `forms.subscribe` refuses one whose domain takes no mail
+  with the field error `undeliverable`. `settings['refuseDisposable']` also refuses throwaway
+  addresses (`disposable`), `settings['checkMailbox']` runs a deep check on every sign-up and
+  refuses a missing mailbox (`mailbox_not_found`), and a refused address that looks like a typo
+  carries `suggestion`.

nextmail-0.0.1/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: nextmail
+Version: 0.0.1
+Summary: The official Python SDK for the Nextmail API. Send email and broadcasts, work with threads, drafts, labels, templates, rules, webhooks, tracking, contacts, audiences, sign-up forms, domains, suppressions, files, API keys, roles, members, mailbox imports and disposable inboxes from code.
+Project-URL: Homepage, https://nextmail.sh
+Project-URL: Documentation, https://nextmail.sh/docs/python
+Project-URL: Reference, https://nextmail.sh/docs/python/reference/methods
+Project-URL: Changelog, https://nextmail.sh/docs/python/changelog
+Project-URL: Support, https://nextmail.sh/contact
+Author: Nextmail
+License-Expression: LicenseRef-Proprietary
+Keywords: api,api client,email,email api,email templates,inbox,mailbox,nextmail,sdk,send email,temp mail,transactional email,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=3.7
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.12
+Description-Content-Type: text/markdown
+
+<div align='center'>
+   <a href='https://nextmail.sh'>
+        <img
+            src='https://nextmail.sh/logo.svg'
+            alt='Nextmail Logo'
+            width='180'
+        />
+   </a>
+
+   <br />
+</div>
+
+<p align='center'>
+    Email you can build on. Send mail, read the mailbox and automate a workspace from code.
+</p>
+
+<p align='center'>
+    <a href='https://nextmail.sh'>
+        <b>
+            Website
+        </b>
+    </a>
+    •
+    <a href='https://nextmail.sh/docs/python'>
+        <b>
+            Documentation
+        </b>
+    </a>
+    •
+    <a href='https://nextmail.sh/docs/python/reference/methods'>
+        <b>
+            Every method
+        </b>
+    </a>
+    •
+    <a href='https://nextmail.sh/docs/api/reference'>
+        <b>
+            API Reference
+        </b>
+    </a>
+</p>
+
+<br />
+
+## Intro to the Python Package
+
+The official Python client for the Nextmail API. It has one method for every method of the TypeScript SDK, under the same names in snake_case, typed end to end. There is a synchronous client and an asynchronous one with the same methods, it runs on Python 3.10 and newer, and it depends only on `httpx`, `anyio` and `typing-extensions`.
+
+It carries a workspace API key or an OAuth access token, so it belongs on a server or in a tool that runs on your own machine. The one exception is disposable inboxes, which need no credential.
+
+### Installing
+```bash
+pip install nextmail
+```
+
+Or `uv add nextmail`, or `poetry add nextmail`.
+
+### Using
+```python
+from nextmail import Nextmail
+
+client = Nextmail('nm_live_...')
+
+sent = client.emails.send(
+    {
+        'from': 'Acme Billing <billing@acme.com>',
+        'to': 'ada@example.com',
+        'subject': 'Your September invoice',
+        'html': '<p>Your invoice is attached.</p>',
+        'attachments': [
+            {'filename': 'invoice.pdf', 'content': pdf_bytes, 'contentType': 'application/pdf'}
+        ],
+    }
+)
+
+print(sent['id'], sent['status'])
+```
+
+Request bodies are plain dictionaries with the API's own field names, so `'from'`, `'scheduledAt'` and `'replyTo'` read exactly as they do in the API reference. Responses are dictionaries too. Every body and response has a `TypedDict` in `nextmail.types`, so your editor completes the keys and a type checker catches a misspelt one.
+
+Create a key in Nextmail under Settings, API keys. It is shown once, and it belongs in an environment variable rather than in code. `Nextmail()` with no key reads `NEXTMAIL_API_KEY`:
+
+```python
+from nextmail import Nextmail
+
+client = Nextmail()
+```
+
+Build the client once, in a module of its own, and import it everywhere else. It keeps one connection pool, is safe to share between threads, and closes with `client.close()` or a `with` block.
+
+Or skip even that. The package ships a ready made `nextmail` client that reads `NEXTMAIL_API_KEY` the first time it is touched:
+
+```python
+from nextmail import nextmail
+
+nextmail.emails.send({'from': sender, 'to': recipient, 'subject': subject, 'text': text})
+```
+
+Every send carries an idempotency key, generated once per call and reused by its retries, so a retried request replays the original message rather than sending a second one. Pass your own with `idempotency_key=` to make that hold across processes and restarts.
+
+### Async
+```python
+import asyncio
+
+from nextmail import AsyncNextmail
+
+
+async def main() -> None:
+    async with AsyncNextmail() as client:
+        sent = await client.emails.send(
+            {'from': sender, 'to': recipient, 'subject': 'Hi', 'text': 'Hello'}
+        )
+
+        async for thread in client.threads.iterate(folder='inbox'):
+            print(thread['id'])
+
+        print(sent['status'])
+
+
+asyncio.run(main())
+```
+
+`AsyncNextmail` has every method `Nextmail` has, with the same arguments, and runs on asyncio and trio.
+
+### Reading the mailbox
+```python
+page = client.threads.list(folder='inbox', limit=25)
+
+for thread in client.threads.iterate(folder='inbox', query='invoice'):
+    full = client.threads.get(thread['id'])
+
+    print(full['messageCount'], full['hasUnread'])
+```
+
+Every paginated resource has `list` for one page, `list_all` for every page at once and `iterate` to stream items and stop whenever you like. A page is `{'items': [...], 'hasMore': ..., 'nextCursor': ...}`, and `list_all` returns one list, apart from `addresses.list_all`, which returns the whole address book.
+
+### Errors
+```python
+from nextmail import NextmailApiError, nextmail
+
+try:
+    nextmail.templates.send(
+        'order-shipped',
+        {
+            'from': 'dispatch@acme.com',
+            'to': 'ada@example.com',
+            'props': {'orderId': 'AC-4192'},
+        },
+    )
+except NextmailApiError as error:
+    if error.is_validation:
+        print(error.code, error.param, error.request_id)
+
+    raise
+```
+
+An API refusal is one class, `NextmailApiError`, with `status`, `type`, `code`, `param` and `request_id`, plus `is_validation`, `is_not_found`, `is_rate_limited` and friends to branch on. No response at all is `NextmailNetworkError`, with `is_timeout` when the deadline passed. Both inherit `NextmailError`. An argument the client can tell is wrong before anything is sent, such as a malformed key, raises `ValueError`.
+
+### Webhooks
+```python
+import os
+
+from fastapi import FastAPI, Request, Response
+from nextmail import verify_webhook_signature
+
+app = FastAPI()
+
+
+@app.post('/webhooks/nextmail')
+async def webhook(request: Request) -> Response:
+    event = verify_webhook_signature(
+        payload=await request.body(),
+        headers=request.headers,
+        secret=os.environ['NEXTMAIL_WEBHOOK_SECRET'],
+    )
+
+    print(event['type'], event['data'])
+
+    return Response(status_code=204)
+```
+
+It checks the HMAC in constant time and rejects a delivery more than five minutes old, then returns the parsed event, or raises `WebhookVerificationError`. Pass the raw body as bytes or text: re-serialising it changes the bytes and the signature will not match. The headers can come from any framework, since the lookup ignores case.
+
+### Disposable inboxes
+```python
+from nextmail import create_temp_mail
+
+temp = create_temp_mail()
+
+inbox = temp.create({'ttlMinutes': 60})
+
+messages = temp.list_messages(inbox['id'], inbox_token=inbox['token'])
+```
+
+`create` needs no credential and is the only call that returns the inbox token, so keep it.
+
+### OAuth access tokens
+An app a person connected to Nextmail with OAuth, such as a command line tool or an agent, holds an access token rather than an API key. Pass it as `access_token`:
+
+```python
+from nextmail import Nextmail
+
+client = Nextmail(access_token=session.fresh_access_token)
+```
+
+`access_token` takes the token itself, or a function that returns it. The function runs before every request, so renew the token there when it is close to expiring and the client never has to be rebuilt. On `AsyncNextmail` the function may also be `async`. Pass `api_key` or `access_token`, not both. `Nextmail()` reads `NEXTMAIL_ACCESS_TOKEN` when you pass neither and `NEXTMAIL_API_KEY` is not set. `me.get()` answers `'object': 'oauth_token'` for a token, with the connected app's `clientId` and `expiresAt`, when the person's approval of the app runs out.
+
+A token acts for a person, so before a sensitive change, such as deleting a domain or changing a webhook, it is asked for the same verification code the web app asks for. The request fails with `is_step_up_required`. Ask for a code, check it, then replay the request:
+
+```python
+from nextmail import NextmailApiError
+
+try:
+    client.domains.delete(domain_id)
+except NextmailApiError as error:
+    if not error.is_step_up_required:
+        raise
+
+    challenge = client.security.begin_step_up()
+
+    if challenge['method'] == 'email':
+        prompt = f'Enter the code we emailed to {challenge.get("sentTo")}: '
+    else:
+        prompt = 'Enter the code from your authenticator app, or a backup code: '
+
+    client.security.verify_step_up({'code': input(prompt)})
+    client.domains.delete(domain_id)
+```
+
+An emailed code works for 10 minutes, and `begin_step_up({'resend': True})` sends a fresh one. Once a code is verified the app is not asked again for 60 minutes. `security.step_up_status()` says whether it is verified right now. API keys are never asked for a code.
+
+### Configuring
+Pass keyword arguments when the defaults are not right:
+
+```python
+import os
+
+import httpx
+from nextmail import Nextmail
+
+client = Nextmail(
+    os.environ['NEXTMAIL_API_KEY'],
+    base_url='https://api.nextmail.sh',
+    timeout=30,
+    max_retries=2,
+    http_client=httpx.Client(proxy='http://proxy.internal:3128', follow_redirects=True),
+    headers={'X-Team': 'billing'},
+)
+```
+
+The shipped `nextmail` client takes the same arguments through `init(...)`, called once at startup.
+
+`base_url` also comes from `NEXTMAIL_BASE_URL`. Use an `https:` origin: the client refuses to send an API key, an access token or an inbox token over plain `http:`, and raises before the request leaves, unless the server is on this machine at `localhost`, a `127.x.x.x` address or `::1`. A `base_url` on `0.0.0.0` raises when the client is built, since that is the address a server listens on: use `127.0.0.1` with the same port.
+
+`timeout` is in seconds and bounds the whole attempt, the response body included, and `0` turns it off. Reads are retried on 408 and 5xx with backoff. A 429 is retried only when it carries a `Retry-After`, and any wait longer than a minute raises instead of sleeping. Writes that cannot safely repeat are not retried. Every method outside `temp_mail` takes `api_key=` and `timeout=`, so one process can serve several workspaces with one client. The `temp_mail` methods take `inbox_token=` instead of `api_key=`.
+
+An endpoint no method wraps yet is one `client.raw.request()` away, with the client's credential, base URL, timeout and retry policy applied:
+
+```python
+result = client.raw.request('/something-new', method='POST', body={'name': 'Invoices'})
+```
+
+The path must begin with a single `/`. Anything else, such as `//host/x`, raises before a request is sent, and so does a path whose finished URL leaves the base URL's origin, so the credential it carries never reaches another host.
+
+When a newer version is on PyPI the client says so once on a terminal. `NEXTMAIL_DISABLE_UPDATE_NOTICE=1` or `disable_update_notice=True` turns that off.