Metadata-Version: 2.4
Name: langchain-qubrics
Version: 1.0.0
Summary: LangChain toolkit for the Qubrics email API for AI agents.
Project-URL: Homepage, https://qubrics.com
Project-URL: Documentation, https://qubrics.com/docs/sdks
Project-URL: Repository, https://github.com/qubrics/qubrics-sdk
Project-URL: Issues, https://github.com/qubrics/qubrics-sdk/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agent,agents,ai-agents,email,email-api,inbox,langchain,langchain-toolkit,llm,mailbox,send-email,sendmux,tools,transactional-email
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: langchain-core<2,>=1.0.0
Requires-Dist: qubrics-mailbox<4.0.0,>=3.0.0
Requires-Dist: qubrics-sending<3.0.0,>=2.0.0
Description-Content-Type: text/markdown

# langchain-qubrics

[LangChain](https://docs.langchain.com) toolkit for [Qubrics](https://qubrics.com), the email API for AI agents.

Gives an agent its own mailbox: it can send email, read what arrives, and reply from its own address.

## Requirements

- Python 3.10 or newer
- `langchain-core` v1

## Installation

These commands target the Qubrics release of `langchain-qubrics`. Until it is published, install `langchain-sendmux` with its existing import names.

```sh
pip install langchain-qubrics
```

## Getting an API key

For API-key authentication, use a key that can both send and receive. Two ways to get one:

- **Dashboard** — create a mailbox and a mailbox-scoped key (`smx_mbx_*`). See [API keys](https://qubrics.com/docs/guides/api-keys).
- **Agent self-registration** — the agent claims its own `@myagent.mx` mailbox and gets an `smx_agent_*` token, with no human signup first. See [email for AI agents](https://qubrics.com/solutions/for-ai-agents/).

Note on agent tokens: a freshly self-registered `smx_agent_*` token can read and receive, but **cannot send** until a human owner has been invited and has approved it. Until then `send_email` and `reply` will fail. A dashboard `smx_mbx_*` key with send permission works immediately.

Read the key from the environment. Never hard-code it.

## OAuth access tokens

Set `access_token` to a bare REST OAuth token or callable instead of `api_key`:

```python
import os
from qubrics.langchain import QubricsToolkit

toolkit = QubricsToolkit(
    access_token=lambda: os.environ["QUBRICS_ACCESS_TOKEN"],
    default_from="agent@yourdomain.dev",
)
tools = toolkit.get_tools()
```

The provider runs before every tool request. Your application owns protected token storage, expiry checks, and refresh coordination. Request `mailbox.read` and `email.send` to use all three tools, and select one mailbox at consent; these tools do not supply a mailbox selector. Credentials are excluded from the toolkit's representation and model serialisation. See [REST OAuth](https://qubrics.com/docs/developer-tools/oauth).

## Quick start

```python
import os

from langchain.agents import create_agent

from qubrics.langchain import QubricsToolkit

smx = QubricsToolkit(
    api_key=os.environ["QUBRICS_API_KEY"],
    default_from="agent@yourdomain.dev",
)

agent = create_agent(
    model="gpt-4o",
    tools=smx.get_tools(),
    system_prompt="You triage the support inbox.",
)

agent.invoke(
    {"messages": [{"role": "user", "content": "Reply to anyone asking about pricing."}]}
)
```

## Tools

`QubricsToolkit(...).get_tools()` returns three tools.

### `send_email`

Sends through your configured sending providers, to any recipient.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `to` | str | yes | Recipient email address |
| `subject` | str | yes | Subject line |
| `text` | str | yes | Plain-text body |
| `html` | str | no | HTML body. Generated from `text` if omitted |
| `var_from` | str | no | Sender address. Falls back to `default_from` |
| `idempotency_key` | str | no | Makes a retried send idempotent for 24 hours |
| `delivery_group` | str or list[str] | no | One delivery group ID, or a list of IDs, that narrows the eligible provider pool for this send. Omit to keep the default routing |

`var_from` is spelt that way because `from` is a reserved word in Python.

### `list_messages`

Lists messages in the agent's own mailbox, newest first.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | int | no | How many to return, 1 to 100. Defaults to 25 |

### `reply`

Sends from the agent's own mailbox address, rather than through a sending provider. Use this to answer someone who wrote in.

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `to` | str | yes | Recipient email address |
| `subject` | str | yes | Subject line |
| `text` | str | yes | Plain-text body |
| `html` | str | no | HTML body. Generated from `text` if omitted |
| `idempotency_key` | str | no | Makes a retried send idempotent for 24 hours |

## Configuration

```python
QubricsToolkit(api_key=..., default_from=...)
```

| Option | Required | Purpose |
| --- | --- | --- |
| `api_key` | Required unless `access_token` is set | A send + receive mailbox key (`smx_mbx_*`) or a scoped agent token (`smx_agent_*`) |
| `access_token` | Required unless `api_key` is set | A bare REST OAuth token or callable returning the current token; supply exactly one credential option |
| `default_from` | no | Default sender for `send_email`. Without it, the model has to supply `var_from` on every call |

## Retries and duplicate sends

Agents retry. Pass `idempotency_key` on `send_email` and `reply` and Qubrics will send once, even if the same call arrives several times inside 24 hours. Any stable string works — a task id, a thread id, a hash of the message.

Details: [idempotency](https://qubrics.com/docs/guides/idempotency).

## Common errors

| What you see | Why | Fix |
| --- | --- | --- |
| `ValueError: No sender address` | No `var_from` on the call and no `default_from` set | Set `default_from`, or have the model pass `var_from` |
| Send rejected on an agent token | The token is self-registered and not yet owner-approved | Complete the owner invite and approval |
| Auth failure | Key lacks send or receive permission | Check the key's scope in the dashboard |

## Related

- [Quickstart](https://qubrics.com/docs/guides/quickstart)
- [Mailboxes](https://qubrics.com/docs/guides/mailboxes)
- [All Qubrics SDKs](https://qubrics.com/docs/sdks)
- [Pricing](https://qubrics.com/pricing/) — usage-based, no per-seat or per-mailbox fees

## Licence

MIT. See the [licence file](https://github.com/qubrics/qubrics-sdk/blob/main/LICENSE).
