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 toONESEND_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-Afteris honored. - Errors carry the API's
type,code,messageanddetails. - Responses use the REST field names (camelCase).
/openapi.jsonon 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.
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/.