SDKs

Each SDK covers the full public REST API, including mailboxes, sender display names, messages, threads, attachments, domains, webhooks and event streaming. Use the same account, mailboxes and API keys across your applications. Your existing plan limits apply.

• TypeScript / JavaScript (Node.js 20.3+)
• Python (Python 3.10+)
• Go (Go 1.22+)
• Ruby (Ruby 3.1+)
• Rust (Rust 1.88+ and Tokio)

Version v0.1.0 is available from the public GitHub repositories below. Use these pinned installation commands; npm, PyPI, RubyGems and crates.io packages are not yet published. Go modules install directly from the repository tag. All five SDKs are open source under the MIT license.

1. Create a Robotomail account and verify your email.
2. Open Settings in your dashboard and create an API key in the API keys section. Copy it when it is shown.
3. Set ROBOTOMAIL_API_KEY in your application's environment. Every client below reads it automatically.

Keep the key on your server and out of source control. Use a mailbox-scoped key when your app only needs selected mailboxes. Account operations and attachment uploads require a full-access key.

The examples list your mailbox addresses without sending email. On the Free plan, test sends and replies with your verified email address. See pricing for current allowances.

Connecting an existing agent such as Claude or Hermes? Follow the MCP setup guide for browser-approved access. SDKs authenticate directly to the REST API with your API key.

Requires Node.js 20.3+. Supports TypeScript and JavaScript, with ESM and CommonJS. Run the client on your server.

Install

npm install github:robotomail/robotomail-node#v0.1.0

List your mailboxes

import { Robotomail } from "@robotomail/sdk";

const mail = new Robotomail(); // reads ROBOTOMAIL_API_KEY
const { mailboxes } = await mail.listMailboxes();
console.log(mailboxes.map(box => box.fullAddress));

Source & examples · API method reference · Sending, streaming & webhook guide

Requires Python 3.10+. Includes synchronous Robotomail and asynchronous AsyncRobotomail clients. Response dictionary keys match the API field names.

Install

pip install "robotomail @ git+https://github.com/robotomail/robotomail-python.git@v0.1.0"

List your mailboxes

from robotomail import Robotomail

with Robotomail() as mail:  # reads ROBOTOMAIL_API_KEY
    result = mail.list_mailboxes()
    print([box["fullAddress"] for box in result["mailboxes"]])

Source & examples · API method reference · Sending, streaming & webhook guide

Requires Go 1.22+. Uses the Go standard library with no runtime dependencies. Requests accept context.Context for cancellation and deadlines.

Install

go get github.com/robotomail/robotomail-go@v0.1.0

List your mailboxes

package main

import (
    "context"
    "fmt"
    "log"
    robotomail "github.com/robotomail/robotomail-go"
)

func main() {
    mail, err := robotomail.NewClient(robotomail.Options{}) // reads ROBOTOMAIL_API_KEY
    if err != nil { log.Fatal(err) }
    result, err := mail.ListMailboxes(context.Background())
    if err != nil { log.Fatal(err) }
    for _, box := range result.Mailboxes { fmt.Println(box.FullAddress) }
}

Source & examples · API method reference · Sending, streaming & webhook guide

Requires Ruby 3.1+. Add the dependency to your Gemfile, then run bundle install. Responses use string-keyed hashes.

Install

# Gemfile
gem "robotomail", git: "https://github.com/robotomail/robotomail-ruby", tag: "v0.1.0"

bundle install

List your mailboxes

require "robotomail"

mail = Robotomail::Client.new # reads ROBOTOMAIL_API_KEY
mail.list_mailboxes["mailboxes"].each { |box| puts box["fullAddress"] }

Source & examples · API method reference · Sending, streaming & webhook guide

Requires Rust 1.88+ and Tokio. Add these entries to your Cargo.toml dependencies. The asynchronous client runs on Tokio and returns typed models.

Install

# Cargo.toml
[dependencies]
robotomail = { git = "https://github.com/robotomail/robotomail-rust", tag = "v0.1.0" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

List your mailboxes

use robotomail::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mail = Client::from_env()?;
    let result = mail.list_mailboxes().await?;
    for mailbox in result.mailboxes { println!("{}", mailbox.full_address); }
    Ok(())
}

Source & examples · API method reference · Sending, streaming & webhook guide

Use a mailbox ID returned by the list operation. Set its displayName to the friendly From name you want people to see, then send a message. For example, with the TypeScript client above:

const mailboxId = "your-mailbox-id";
await mail.updateMailbox(mailboxId, { displayName: "Research Agent" });
await mail.sendMessage(mailboxId, {
  to: ["your-verified-email@example.com"],
  subject: "Hello from my agent",
  bodyText: "Reply to this email to test my inbox."
});

Replace the mailbox ID and recipient before running. Each repository's guide shows the equivalent send in that language. Sending happens immediately; API acceptance does not mean delivery has completed.

• Read and reply: list received messages and use the original RFC Message-ID in inReplyTo to preserve the thread.
• Webhooks: receive notifications and verify the signature using your SDK's helper with the original raw request body.
• SSE events: stream new events and reopen with Last-Event-ID after a disconnect. SDK streams do not reconnect automatically.
• Attachments: upload a file and pass its ID in the send request's attachments array.

HTTP errors include the status, response body and headers. Check the error reference for permission, quota and rate-limit responses. Normal requests default to a 30-second timeout; streams allow longer connections.

SDKs do not automatically retry sends. If a request times out after acceptance, inspect your sent messages before trying again to avoid a duplicate. Paginate message lists explicitly using limit and offset; retain message IDs when scanning a changing inbox.

The default API base URL is https://api.robotomail.com/v1. Each client supports a custom base URL for testing. For the underlying contract, see the OpenAPI specification. This guide is also available as Markdown for agents.