Official SDKs — Python, Node.js, Ruby & Go

Ark provides official, fully-typed SDKs in four languages, plus an MCP server for AI assistants. All SDKs offer consistent behavior, complete API coverage, and excellent developer experience.

AI Assistants (MCP)

MCP Server

New: Use Ark with Claude, Cursor, VS Code, and other AI assistants. Send emails using natural language — no code required.

"Send a welcome email to user@example.com"

Language SDKs

Python

pip install ark-email — Python 3.9+ with async support

Node.js

npm install ark-email — TypeScript-first with full types

Ruby

gem install ark-email — Ruby 3.2+ with Sorbet types

Go

go get github.com/ArkHQ-io/ark-go — Go 1.22+

Quick Installation

Python
Node.js
Ruby
Go

pip install ark-email

For async support with aiohttp:

pip install ark-email[aiohttp]

npm install ark-email

Or with your preferred package manager:

yarn add ark-email
pnpm add ark-email

gem install ark-email

Or add to your Gemfile:

gem "ark-email", "~> 0.5"

go get github.com/ArkHQ-io/ark-go

Send Your First Email

Python
Node.js
Ruby
Go

import os
from ark import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

email = client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Hello from Ark!",
    html="<h1>Welcome!</h1><p>You're all set.</p>"
)

print(f"Email sent: {email.data.id}")

import Ark from 'ark-email';

const client = new Ark({
  apiKey: process.env.ARK_API_KEY,
});

const email = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Hello from Ark!',
  html: '<h1>Welcome!</h1><p>You\'re all set.</p>',
});

console.log(`Email sent: ${email.data.id}`);

require "ark_email"

client = ArkEmail::Client.new(api_key: ENV["ARK_API_KEY"])

email = client.emails.send_(
  from: "hello@yourdomain.com",
  to: ["user@example.com"],
  subject: "Hello from Ark!",
  html: "<h1>Welcome!</h1><p>You're all set.</p>"
)

puts "Email sent: #{email.data.id}"

Ruby uses send_ (with underscore) because send is a reserved method in Ruby.

package main

import (
    "context"
    "fmt"
    "github.com/ArkHQ-io/ark-go"
    "github.com/ArkHQ-io/ark-go/option"
)

func main() {
    client := ark.NewClient(
        option.WithAPIKey("your-api-key"), // or use ARK_API_KEY env var
    )

    email, err := client.Emails.Send(context.Background(), ark.EmailSendParams{
        From:    "hello@yourdomain.com",
        To:      []string{"user@example.com"},
        Subject: "Hello from Ark!",
        HTML:    ark.String("<h1>Welcome!</h1><p>You're all set.</p>"),
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Email sent: %s\n", email.Data.ID)
}

SDK Features

All official Ark SDKs share these capabilities:

Full Type Safety

Every SDK includes complete type definitions. Python has full type hints, Node.js has TypeScript definitions, Ruby has Sorbet RBI files, and Go has native types.Your IDE will provide autocomplete, inline documentation, and catch errors before runtime.

Automatic Retries

SDKs automatically retry failed requests with exponential backoff for:

Connection errors
408 Request Timeout
409 Conflict
429 Rate Limit
5xx Server Errors

Default: 2 retries. Configurable per-client or per-request.

Configurable Timeouts

Default timeout is 60 seconds. Customize globally or per-request:

Python
Node.js
Ruby
Go

client = Ark(timeout=30.0)  # 30 seconds

# Per-request
client.emails.send(..., timeout=10.0)

const client = new Ark({ timeout: 30000 }); // 30 seconds

// Per-request
await client.emails.send({...}, { timeout: 10000 });

client = ArkEmail::Client.new(timeout: 30)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
client.Emails.Send(ctx, params)

Error Handling

SDKs throw typed exceptions for different error scenarios:

Status	Exception
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
422	`UnprocessableEntityError`
429	`RateLimitError`
5xx	`InternalServerError`
Network	`APIConnectionError`

Raw Response Access

Access HTTP headers, status codes, and raw response data when needed:

Python
Node.js
Go

response = client.emails.with_raw_response.send(...)
print(response.headers)
email = response.parse()

const { data, response } = await client.emails.send({...}).withResponse();
console.log(response.headers);

var response *http.Response
email, _ := client.Emails.Send(ctx, params,
    option.WithResponseInto(&response))

Debug Logging

Enable debug logging to troubleshoot issues:

Python
Node.js

export ARK_LOG=debug

Or in code:

import logging
logging.getLogger("ark").setLevel(logging.DEBUG)

export ARK_LOG=debug

Or in code:

const client = new Ark({ logLevel: 'debug' });

Async Support

Python
Node.js
Ruby
Go

import asyncio
from ark import AsyncArk

async def main():
    client = AsyncArk()

    email = await client.emails.send(
        from_="hello@yourdomain.com",
        to=["user@example.com"],
        subject="Async email!",
        html="<p>Sent asynchronously</p>"
    )
    print(f"Sent: {email.data.id}")

asyncio.run(main())

Install with pip install ark-email[aiohttp] for best async performance.

Node.js SDK is async by default. All methods return Promises:

// Already async!
const email = await client.emails.send({...});

// Or with .then()
client.emails.send({...}).then(email => {
  console.log(email.data.id);
});

Ruby SDK uses synchronous HTTP by default but is thread-safe:

# Thread-safe - use a single client instance
client = ArkEmail::Client.new(api_key: ENV["ARK_API_KEY"])

threads = 10.times.map do |i|
  Thread.new do
    client.emails.send_(
      from: "hello@yourdomain.com",
      to: ["user#{i}@example.com"],
      subject: "Thread #{i}",
      html: "<p>Hello from thread #{i}</p>"
    )
  end
end

threads.each(&:join)

Go is concurrent by default with goroutines:

var wg sync.WaitGroup

for i := 0; i < 10; i++ {
    wg.Add(1)
    go func(n int) {
        defer wg.Done()
        client.Emails.Send(ctx, ark.EmailSendParams{
            From:    "hello@yourdomain.com",
            To:      []string{fmt.Sprintf("user%d@example.com", n)},
            Subject: fmt.Sprintf("Goroutine %d", n),
            HTML:    ark.String("<p>Hello from goroutine</p>"),
        })
    }(i)
}

wg.Wait()

Tenant-Scoped Operations

If you’re building a white-label email platform, every SDK supports tenant-scoped operations. Pass a tenant_id to send emails, manage domains, and configure webhooks on behalf of your customers:

Python
Node.js
Ruby
Go

# Send email on behalf of a tenant
email = client.emails.send(
    from_="hello@customer-domain.com",
    to=["user@example.com"],
    subject="Order Confirmed",
    html="<p>Your order has been confirmed.</p>",
    tenant_id="tenant_abc123"
)

# Create a domain for a tenant
domain = client.domains.create(
    name="mail.customer-domain.com",
    tenant_id="tenant_abc123"
)

// Send email on behalf of a tenant
const email = await client.emails.send({
  from: 'hello@customer-domain.com',
  to: ['user@example.com'],
  subject: 'Order Confirmed',
  html: '<p>Your order has been confirmed.</p>',
  tenantId: 'tenant_abc123',
});

// Create a domain for a tenant
const domain = await client.domains.create({
  name: 'mail.customer-domain.com',
  tenantId: 'tenant_abc123',
});

# Send email on behalf of a tenant
email = client.emails.send_(
  from: "hello@customer-domain.com",
  to: ["user@example.com"],
  subject: "Order Confirmed",
  html: "<p>Your order has been confirmed.</p>",
  tenant_id: "tenant_abc123"
)

# Create a domain for a tenant
domain = client.domains.create(
  name: "mail.customer-domain.com",
  tenant_id: "tenant_abc123"
)

// Send email on behalf of a tenant
email, _ := client.Emails.Send(ctx, ark.EmailSendParams{
    From:     "hello@customer-domain.com",
    To:       []string{"user@example.com"},
    Subject:  "Order Confirmed",
    HTML:     ark.String("<p>Your order has been confirmed.</p>"),
    TenantID: ark.String("tenant_abc123"),
})

// Create a domain for a tenant
domain, _ := client.Domains.Create(ctx, ark.DomainCreateParams{
    Name:     "mail.customer-domain.com",
    TenantID: ark.String("tenant_abc123"),
})

New to white-label? Start with the Architecture Overview to understand how Platform → Tenant → Domain → Email hierarchy works. Then see Tenant Management for full CRUD operations.

Source Code & Issues

All SDKs are open source. Report issues or contribute:

SDK	Repository	License
Python	github.com/ArkHQ-io/ark-python	Apache-2.0
Node.js	github.com/ArkHQ-io/ark-nodejs	Apache-2.0
Ruby	github.com/ArkHQ-io/ark-ruby	Apache-2.0
Go	github.com/ArkHQ-io/ark-go	Apache-2.0

Next Steps

MCP Server

Use Ark with AI assistants like Claude and Cursor

Architecture Overview

Understand Platform → Tenant → Domain → Email hierarchy

Python SDK

Complete Python documentation with async patterns

Node.js SDK

TypeScript examples and framework integrations

Ruby SDK

Rails integration and Sorbet type safety

Go SDK

Idiomatic Go patterns and context usage

Documentation Index

​AI Assistants (MCP)

MCP Server

​Language SDKs

Python

Node.js

Ruby

Go

​Quick Installation

​Send Your First Email

​SDK Features

​Async Support

​Tenant-Scoped Operations

​Source Code & Issues

​Next Steps

MCP Server

Architecture Overview

Python SDK

Node.js SDK

Ruby SDK

Go SDK

AI Assistants (MCP)

Language SDKs

Quick Installation

Send Your First Email

SDK Features

Async Support

Tenant-Scoped Operations

Source Code & Issues

Next Steps