nextmail 0.0.2__tar.gz

nextmail-0.0.2/.gitignore

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

nextmail-0.0.2/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.0.2
+
+- API keys begin `nm_live_` or `nm_test_`, and temporary inbox tokens `nm_inbox_`. The client
+  refuses a key of any other shape, and a key created before this release no longer works: create a
+  new one in the app or with `keys.create`.
+- 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.
+
+## 0.0.1
+
+The first release of the Python package. It has a method for every one of the 684 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`.

nextmail-0.0.2/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: nextmail
+Version: 0.0.2
+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.

nextmail-0.0.2/README.md

@@ -0,0 +1,265 @@
+<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.