# SDKs for other languages

Use Python, PHP, Go and Ruby clients for the public email API.

Source: https://docs.ravenrelay.joshlab.site/language-sdks

Agent index: https://docs.ravenrelay.joshlab.site/llms.txt
OpenAPI: https://docs.ravenrelay.joshlab.site/openapi.json

## Choose a client

> The Node.js SDK is published on npm. Python 0.1.0 is available on PyPI as ravenrelay, and PHP 0.1.0 is available on Packagist as ravenrelay/php. Go v0.1.0 is available as github.com/joshmoy/ravenrelay-go. Ruby 0.1.0 is available on RubyGems as ravenrelay.

| Language | Runtime | Source directory | Package name |
| --- | --- | --- | --- |
| Python | 3.9+ | sdks/python | ravenrelay (PyPI, 0.1.0) |
| PHP | 8.1+ with cURL | sdks/php | ravenrelay/php (Packagist, 0.1.0) |
| Go | 1.22+ | sdks/go | github.com/joshmoy/ravenrelay-go |
| Ruby | 3.1+ | sdks/ruby | ravenrelay (RubyGems, 0.1.0) |

## Shared behavior

Every client supports HTML/text sending, saved project templates with variables, email detail reads, filtered email lists with cursors, and webhook signature verification. Responses preserve the public API field names. React Email rendering and starter React components belong to the Node.js SDK; render HTML in your application when using another language.

1. Set the API origin explicitly to your deployment and keep API keys server-side.
2. Use an idempotency key for sends. Clients do not automatically retry sends; a transport failure can leave acceptance uncertain. Reuse the same key and identical body when retrying.
3. API exceptions expose HTTP status and error code. Invalid successful responses raise protocol errors. The default timeout is ten seconds, including response reads. Source clients require HTTPS for remote origins, refuse redirects and limit response size and JSON nesting.
4. Verify webhook signatures against the original body bytes before parsing JSON. Verification uses HMAC-SHA256 and a five-minute timestamp tolerance. Durably deduplicate event IDs and accept out-of-order events.

## Ruby installation

Install from RubyGems

```
gem install ravenrelay
```

Use Bundler

```
gem 'ravenrelay', '~> 0.1'
```

Ruby 3.1 or later is required. Load the client with require 'ravenrelay'. The SDK includes reviewed, pinned HTTP, JSON and TLS dependencies; keep your application's Gemfile.lock committed.

## Go installation

Install the Go module

```
go get github.com/joshmoy/ravenrelay-go@v0.1.0
```

Import the client

```
import "github.com/joshmoy/ravenrelay-go"
```

Go 1.22 or later is required. The SDK uses only the standard library; the Go SDK README contains sending, reading and webhook examples.

## PHP example

Install from Packagist

```
composer require ravenrelay/php
```

Send from PHP

```
require __DIR__ . '/vendor/autoload.php';

use RavenRelay\RavenRelay;

$client = new RavenRelay(getenv('RAVENRELAY_API_KEY'), 'https://api-production-1c6a.up.railway.app');
$accepted = $client->emails->send([
    'from' => 'hello@example.com',
    'to' => 'user@example.com',
    'subject' => 'Welcome',
    'text' => 'Hello from RavenRelay',
], idempotencyKey: 'welcome-user-123');
$email = $client->emails->get($accepted['id']);
```

PHP requires version 8.1 or later with the cURL and JSON extensions. The SDK has no third-party Composer dependencies.

## Python example

Install from PyPI

```
pip install ravenrelay
```

Send from Python

```
import os
from ravenrelay import RavenRelay

client = RavenRelay(
    os.environ['RAVENRELAY_API_KEY'],
    base_url='https://api-production-1c6a.up.railway.app',
)
accepted = client.emails.send({
    'from': 'hello@example.com',
    'to': 'user@example.com',
    'subject': 'Welcome',
    'text': 'Hello from RavenRelay',
}, idempotency_key='welcome-user-123')
email = client.emails.get(accepted['id'])
```

The README in each SDK directory contains its language's send/read examples, error handling contract, webhook verifier and test command.