Skip to main content

langchain-qubrics

LangChain toolkit for Qubrics, 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.

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.
  • 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.

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:

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.

Quick start

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

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.

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

Licence

MIT. See the licence file.

Metadata

Release files for langchain-qubrics 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langchain-qubrics 1.0.0
File Size Uploaded Provenance Actions
langchain_qubrics-1.0.0.tar.gz 5.7 kB Without provenance Details for langchain_qubrics-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langchain-qubrics 1.0.0
File Interpreter ABI Platform Actions
langchain_qubrics-1.0.0-py3-none-any.whl Python 3 none any Details for langchain_qubrics-1.0.0-py3-none-any.whl

Total release size: 12.5 kB

Release files / langchain_qubrics-1.0.0.tar.gz

Download URL langchain_qubrics-1.0.0.tar.gz
Size 5.7 kB
Tags Source
SHA-256 checksum
How to use checksums
7219efeb18fdadfc5238081d31cbacf4d54d31ef2e727e697df49e58df5a2e8d
BLAKE2b-256 checksum
How to use checksums
b29583ed8afc998aebd831532d47a6f6a10b2279f12f9065f8231b6d689e57ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / langchain_qubrics-1.0.0-py3-none-any.whl

Download URL langchain_qubrics-1.0.0-py3-none-any.whl
Size 6.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8feb67c473a7c23d612fa8a078bfdd47d0d1dbea1fc79b38b919d7124c86c1be
BLAKE2b-256 checksum
How to use checksums
e8a6283b600ed66038da3143487f199e1619a1e97d103110f27dbd155bac4997
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for langchain-qubrics 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page