Docs / Developers and AI

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.
LanguageFolderDependenciesTests
TypeScript (and the onesend CLI)packages/sdknone (fetch)npx vitest run packages/sdk
Python 3.9+packages/sdk-pythonstandard librarycd packages/sdk-python && python3 -m unittest discover -s tests
Go 1.21+packages/sdk-gostandard librarycd packages/sdk-go && go test ./...
PHP 8.1+packages/sdk-phpext-curl, ext-jsonphp packages/sdk-php/tests/run.php

TypeScript

See SDK and CLI.

Python

See packages/sdk-python/README.md.

Go

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

// go.mod
require github.com/corepivot/onesend-go v0.0.0
replace github.com/corepivot/onesend-go => ../onesend/packages/sdk-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:

{
  "repositories": [{ "type": "path", "url": "../onesend/packages/sdk-php" }],
  "require": { "corepivot/onesend-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/.