# SDKs

Send, receive and manage email in TypeScript, JavaScript, Python, Go, Ruby or Rust with the official Robotomail SDKs.

## Choose your language

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](https://robotomail.com/docs/sdks#typescript) (Node.js 20.3+)
- [Python](https://robotomail.com/docs/sdks#python) (Python 3.10+)
- [Go](https://robotomail.com/docs/sdks#go) (Go 1.22+)
- [Ruby](https://robotomail.com/docs/sdks#ruby) (Ruby 3.1+)
- [Rust](https://robotomail.com/docs/sdks#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.


## Set your API key

1. [Create a Robotomail account](https://robotomail.com/sign-up) and verify your email.
2. Open [Settings](https://robotomail.com/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](https://robotomail.com/docs/authentication) 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](https://robotomail.com/pricing) for current allowances.

Connecting an existing agent such as Claude or Hermes? Follow the [MCP setup guide](https://robotomail.com/docs/mcp) for browser-approved access. SDKs authenticate directly to the REST API with your API key.


## TypeScript / JavaScript

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

### Install

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

### List your mailboxes

```typescript
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](https://github.com/robotomail/robotomail-node/tree/v0.1.0) · [API method reference](https://github.com/robotomail/robotomail-node/blob/v0.1.0/API.md) · [Sending, streaming & webhook guide](https://github.com/robotomail/robotomail-node/tree/v0.1.0#readme)


## Python

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

### Install

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

### List your mailboxes

```python
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](https://github.com/robotomail/robotomail-python/tree/v0.1.0) · [API method reference](https://github.com/robotomail/robotomail-python/blob/v0.1.0/API.md) · [Sending, streaming & webhook guide](https://github.com/robotomail/robotomail-python/tree/v0.1.0#readme)


## Go

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

### Install

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

### List your mailboxes

```go
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](https://github.com/robotomail/robotomail-go/tree/v0.1.0) · [API method reference](https://github.com/robotomail/robotomail-go/blob/v0.1.0/API.md) · [Sending, streaming & webhook guide](https://github.com/robotomail/robotomail-go/tree/v0.1.0#readme)


## Ruby

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

### Install

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

```shell
bundle install
```

### List your mailboxes

```ruby
require "robotomail"

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

[Source & examples](https://github.com/robotomail/robotomail-ruby/tree/v0.1.0) · [API method reference](https://github.com/robotomail/robotomail-ruby/blob/v0.1.0/API.md) · [Sending, streaming & webhook guide](https://github.com/robotomail/robotomail-ruby/tree/v0.1.0#readme)


## Rust

**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

```toml
# 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

```rust
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](https://github.com/robotomail/robotomail-rust/tree/v0.1.0) · [API method reference](https://github.com/robotomail/robotomail-rust/blob/v0.1.0/API.md) · [Sending, streaming & webhook guide](https://github.com/robotomail/robotomail-rust/tree/v0.1.0#readme)


## Send, receive and reply

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:

```typescript
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](https://robotomail.com/docs/api/messages): list received messages and use the original RFC Message-ID in `inReplyTo` to preserve the thread.
- [Webhooks](https://robotomail.com/docs/concepts/webhooks): receive notifications and verify the signature using your SDK's helper with the original raw request body.
- [SSE events](https://robotomail.com/docs/api/events): stream new events and reopen with `Last-Event-ID` after a disconnect. SDK streams do not reconnect automatically.
- [Attachments](https://robotomail.com/docs/concepts/attachments): upload a file and pass its ID in the send request's `attachments` array.


## Errors, pagination and timeouts

HTTP errors include the status, response body and headers. Check the [error reference](https://robotomail.com/docs/api/errors) 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](https://robotomail.com/openapi.json). This guide is also available as [Markdown for agents](https://robotomail.com/docs/sdks.md).


---

Previous: [MCP & connectors](https://robotomail.com/docs/mcp.md) | Next: [Mailboxes](https://robotomail.com/docs/concepts/mailboxes.md)