SDKs
Official client libraries for integrating with the TopSend API.
TypeScript / Node.js
The official TopSend SDK for TypeScript and Node.js provides a fully typed client with built-in error handling, pagination helpers, and idempotency support.
Installation
npm install @topsend/sdk
Quick Start
# The SDK is for Node.js/TypeScript.# For shell scripts, use cURL directly:curl https://api.topsend.com/api/v1/health \-H "Authorization: Bearer tm_live_abc123"
Available Resources
The SDK provides typed methods for all API resources.
| Resource | Methods | Description |
|---|---|---|
| topsend.contacts | list, get, create, update, delete | Manage contacts and their attributes |
| topsend.lists | list, get, create, update, delete, addMembers, removeMembers | Manage contact lists and memberships |
| topsend.email | send, batch, getStatus, getBatchStatus | Send emails and check delivery status |
| topsend.suppressions | list, add, remove | Manage the email suppression list |
| topsend.webhooks | subscribe, unsubscribe, test | Manage webhook subscriptions |
| topsend.tracking | productView | Track product views and browsing behavior |
| topsend.conversions | list, create | Track revenue and conversion events |
| topsend.segments | list, get, create, update, delete, estimateCount, listContacts | Create and manage audience segments |
| topsend.tags | list, get, create, update, delete, contacts.assign, contacts.remove | Tag contacts for organization and automation |
| topsend.automations | list, get, activate, pause, trigger, listRuns | Control automation workflows programmatically |
| topsend.health | check | Check API and service health status |
Error Handling
The SDK throws typed errors that you can catch and handle programmatically.
# Check the HTTP status code and error response body:# {"error": {"code": "validation_error", "message": "..."}}
Configuration
The SDK accepts an optional configuration object for customizing behavior.
# cURL does not use the SDK configuration.# Set the base URL and headers directly:curl https://api.topsend.com/api/v1/health \-H "Authorization: Bearer tm_live_abc123"
Idempotency
For send and batch endpoints, pass an idempotency key to prevent duplicate operations from network retries.
curl -X POST https://api.topsend.com/api/v1/email/send \-H "Authorization: Bearer tm_live_abc123" \-H "Idempotency-Key: order-confirmation-12345" \-H "Content-Type: application/json" \-d '{"to": "user@example.com", "subject": "Order confirmed", "html": "<p>Done!</p>"}'