Overview

Copied
Previous Next

Official SDKs for integrating with Sema.

Installation

pip install sema-sdk

npm install @withsema/sdk

API keys and environment

Create keys in the dashboard (API keys). Use sk_test_... for development and sk_live_... for production. In production, use environment variables (e.g. SEMA_API_KEY, SEMA_BASE_URL) or a secrets manager - do not hardcode or commit API keys.

Configuration

The client reads configuration from the environment when not provided explicitly. Default base URL when not set: https://dev-api.withsema.com.

Variable Description Used when
SEMA_API_KEY API key (sk_test_... or sk_live_...) apiKey / api_key not passed
SEMA_BASE_URL API base URL baseUrl / base_url not passed

Explicit constructor arguments take precedence over environment variables.

Use an HTTPS base URL in production. The client rejects live keys with a non-HTTPS public base URL and warns for other HTTP base URLs.

What's Included

Each SDK provides:

Feature Description
API Client Create inboxes, upload items, check deliveries
Pagination Iterators Async iterators for processing large result sets
Webhook Verifier Validate signatures, enforce timestamp tolerance, parse payloads
Observability Hooks Optional callbacks for logging, tracing, and metrics
Automatic Retries Exponential backoff for transient failures and rate limits
TypeScript/Pydantic Types Full type safety for all API responses and webhook events

Quick Example

Below, the API key is passed explicitly for clarity. In production, omit it and set SEMA_API_KEY (and optionally SEMA_BASE_URL) in the environment.

from sema_sdk import SemaClient, WebhookVerifier

# Send content (use env SEMA_API_KEY in production)
async with SemaClient(api_key="sk_live_...") as client:
    inbox = await client.create_inbox(name="My Inbox")
    item = await client.upload_item(inbox.id, b"Hello!", sender_address="a@b.com")

# Receive webhooks
verifier = WebhookVerifier(secret="whsec_...")
event = verifier.verify(request.body, request.headers)
print(event.payload.item_id)  # Use event.webhook_id as idempotency key

import { SemaClient, WebhookVerifier } from '@withsema/sdk';

// Send content (use env SEMA_API_KEY in production)
const client = new SemaClient({ apiKey: 'sk_live_...' });
const inbox = await client.createInbox({ name: 'My Inbox' });
const item = await client.uploadItem(inbox.id, buffer, { sender_address: 'a@b.com' });

// Receive webhooks
const verifier = new WebhookVerifier('whsec_...');
const event = verifier.verify(req.body, req.headers);
console.log(event.payload.item_id); // Use event.webhookId as idempotency key

Requirements

SDK Requirements
Python Python 3.10+
Node.js Node.js 18+

Next Steps

Examples Python