---
title: "SDKs"
description: "OneSend includes four client libraries: TypeScript, Python, Go and PHP. They ship with OneSend and are installed from your copy of it, as shown for each language below, not from npm, PyPI, the Go proxy or Packagist."
url: https://onesend.email/docs/sdks/
---
# SDKs

OneSend includes four client libraries: TypeScript, Python, Go and PHP. They ship with OneSend and are installed from your copy of it, as shown for each language below, not from npm, PyPI, the Go proxy or Packagist.

All four behave the same way:

- There is no default server. Set the base URL (or `ONESEND_BASE_URL`), so the API key only goes to a server you chose. The API key falls back to `ONESEND_API_KEY`.
- Every mutating request carries an `Idempotency-Key` (generated, or the one you pass), the same key on every retry, so a retry never sends an email twice.
- Network errors, 408, 429 and 5xx responses are retried twice by default with exponential backoff; `Retry-After` is honored.
- Errors carry the API's `type`, `code`, `message` and `details`.
- Responses use the REST field names (camelCase). `/openapi.json` on your server is the full schema.

| Language | Folder | Dependencies | Tests |
|---|---|---|---|
| TypeScript (and the `onesend` CLI) | `packages/sdk` | none (fetch) | `npx vitest run packages/sdk` |
| Python 3.9+ | `packages/sdk-python` | standard library | `cd packages/sdk-python && python3 -m unittest discover -s tests` |
| Go 1.21+ | `packages/sdk-go` | standard library | `cd packages/sdk-go && go test ./...` |
| PHP 8.1+ | `packages/sdk-php` | ext-curl, ext-json | `php packages/sdk-php/tests/run.php` |

## TypeScript

See [SDK and CLI](https://onesend.email/docs/sdk-and-cli/).

## Python

See [packages/sdk-python/README.md](https://onesend.email/docs/sdk-python/).

## Go

The module path is `github.com/corepivot/onesend-go`. Use it from your copy with a `replace` directive:

```go
// go.mod
require github.com/corepivot/onesend-go v0.0.0
replace github.com/corepivot/onesend-go => ../onesend/packages/sdk-go
```

```go
client, err := onesend.New("os_live_…", onesend.WithBaseURL("http://localhost:3000"))
if err != nil { log.Fatal(err) }
sent, err := client.Emails.Send(ctx, onesend.SendEmailParams{
	From: "Acme <hello@acme.dev>", To: []string{"ada@example.com"},
	Template: "welcome-email", Variables: map[string]any{"first_name": "Ada"},
}, onesend.WithIdempotencyKey("signup-42"))
var apiErr *onesend.Error
if errors.As(err, &apiErr) && apiErr.Code == "validation_failed" { /* … */ }
```

Every method takes a `context.Context`; canceling it stops the request and any retry wait. Services: `Emails` (Send, Batch, Get, List, Cancel, Resend), `Templates` (List, Get, Render), `Domains` (List, Get, Create, Verify, Delete), `Contacts` (List, Upsert, Get, Update, Delete, Erase, Export), `Campaigns` (List, Create, Get, Update, Delete, Test, Schedule, Send, Pause, Resume, Cancel, Report), `Statistics` (Overview), `Events` (Track), `Suppressions` (List, Add, Remove) and `Workspace` (Export, GetExport, DownloadExport). `client.Do` calls any other endpoint. Options: `WithBaseURL`, `WithHTTPClient`, `WithTimeout`, `WithMaxRetries`, `WithHeader`.

## PHP

The Composer package is `corepivot/onesend-php`. Add its folder as a path repository:

```json
{
  "repositories": [{ "type": "path", "url": "../onesend/packages/sdk-php" }],
  "require": { "corepivot/onesend-php": "*" }
}
```

```php
$onesend = new OneSend\OneSend(['apiKey' => 'os_live_…', 'baseUrl' => 'http://localhost:3000']);
try {
    $sent = $onesend->emails->send(['from' => 'Acme <hello@acme.dev>', 'to' => 'ada@example.com', 'template' => 'welcome-email', 'variables' => ['first_name' => 'Ada']], 'signup-42');
} catch (OneSend\OneSendException $e) {
    echo $e->status, ' ', $e->errorCode, ': ', $e->getMessage();
}
```

Namespaces: `emails`, `templates`, `domains`, `contacts` (with `erase` and `export`), `campaigns`, `statistics`, `events` (`track`), `suppressions` and `workspace` (data export). Options: `apiKey`, `baseUrl`, `maxRetries`, `timeout` (seconds), `headers`, and `transport` (an `OneSend\Transport`, for tests or another HTTP client). Without Composer, require the files in `src/` or register a PSR-4 autoloader for `OneSend\` → `src/`.
