Email free

One call, connect_email(), gives your agent a real inbox on @trycaspianai.com, instantly, with no signup and no tokens. Inbound mail reaches your on_message handler; reply() answers in the same thread. When you want your own brand, connect on a verified custom domain instead.

Connect an inbox

Calling connect_email() with no arguments provisions an address on the platform domain. The returned connection carries the live address: print it, or hand it to whoever will email your agent.

from caspian_sdk import CommClient

client = CommClient()                      # reads COMM_API_KEY / COMM_BASE_URL

inbox = client.connect_email()             # a real @trycaspianai.com address
print("Agent address:", inbox["address"])

@client.on_message
def handle(message):
    message.reply(f"Thanks! You said: {message.text}")

client.listen()                            # blocks, dispatching messages forever

import { CommClient } from "caspian-sdk";

const client = new CommClient();                 // reads COMM_API_KEY / COMM_BASE_URL

const inbox = await client.connectEmail();       // a real @trycaspianai.com address
console.log("Agent address:", inbox.address);

client.onMessage(async (message) => {
  await message.reply(`Thanks! You said: ${message.text}`);
});

await client.listen();                           // runs forever; pass an AbortSignal to stop

Receiving and replying

Real emails sent to the inbox arrive at the same on_message handler as every other channel. The fields are identical everywhere:

• message.text: the plain-text body of the email.
• message.sender: who sent it.
• message.conversation_id (message.conversationId in JS): stable per thread, so you can key your agent's memory on it.

message.reply() sends your response back to the original sender. Caspian preserves the email References and In-Reply-To chain automatically, so replies land in the same thread in the recipient's mail client (no headers to set yourself). Reply bodies should be plain text.

@client.on_message
def handle(message):
    answer = your_agent_logic(message.text)   # your LLM / agent framework
    message.reply(answer)                     # threads back to the sender

client.onMessage(async (message) => {
  const answer = await yourAgentLogic(message.text);   // your LLM / agent framework
  await message.reply(answer);                          // threads back to the sender
});

Trigger a test delivery

No mail client handy? test_email() injects a message into your inbox through the gateway, so you can watch your handler run end to end. With your program running in one terminal:

client.test_email(text="hello, are you alive?")

await client.testEmail({ text: "hello, are you alive?" });

Or hit the endpoint directly:

curl -s -X POST https://api.trycaspianai.com/v1/test-emails \
  -H "Authorization: Bearer $COMM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"text":"hello, are you alive?"}'

Within a few seconds your handler fires and sends a reply. Once that works, real emails from any mail client reach the handler the same way.

Use your own domain

By default addresses live on the platform domain. To send from your own brand (kernel@agents.acme.com), first register and verify a dedicated subdomain (see Custom domains), then connect on it. Pass username to pick the exact local part; it is available only on custom domains and returns a 409 if that address is taken.

inbox = client.connect_email(
    domain="agents.acme.com",   # a verified subdomain you control
    username="kernel",          # -> kernel@agents.acme.com
)
print(inbox["address"])

const inbox = await client.connectEmail({
  domain: "agents.acme.com",   // a verified subdomain you control
  username: "kernel",          // -> kernel@agents.acme.com
});
console.log(inbox.address);

Next steps