Official SDKs

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 [email protected]"

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_="[email protected]",
    to=["[email protected]"],
    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: '[email protected]',
  to: ['[email protected]'],
  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: "[email protected]",
  to: ["[email protected]"],
  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:    "[email protected]",
        To:      []string{"[email protected]"},
        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_="[email protected]",
        to=["[email protected]"],
        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: "[email protected]",
      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:    "[email protected]",
            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()

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

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

Overview

Languages

AI Integration

IDE Integrations

Platform Integrations

AI Assistants (MCP)

MCP Server

Language SDKs

Python

Node.js

Ruby

Go

Quick Installation

Send Your First Email

SDK Features

Async Support

Source Code & Issues

Next Steps

MCP Server

Python SDK

Node.js SDK

Ruby SDK

Go SDK

Overview

Languages

AI Integration

IDE Integrations

Platform Integrations

​AI Assistants (MCP)

MCP Server

​Language SDKs

Python

Node.js

Ruby

Go

​Quick Installation

​Send Your First Email

​SDK Features

​Async Support

​Source Code & Issues

​Next Steps

MCP Server

Python SDK

Node.js SDK

Ruby SDK

Go SDK

AI Assistants (MCP)

Language SDKs

Quick Installation

Send Your First Email

SDK Features

Async Support

Source Code & Issues

Next Steps