REST API

Conventions reference for Samva's REST API. Every email send and management call resolves to a request against this API. This page documents the shared conventions — base URL, headers, body and response shapes, status codes, rate limiting, pagination, idempotency, and error format.

For a runnable send walkthrough (curl, Python, Go, PHP), see Send an email. For per-endpoint request and response detail, see the API reference.

Base URL

https://api.samva.app/v1

All endpoints are relative to this base URL.

Authentication

Every request authenticates with an API key passed in the X-API-Key header.

X-API-Key: sk_sm_your_api_key

See Authentication for key format and management.

Headers

Content type

Requests carrying a body must send Content-Type: application/json. All responses are returned as JSON.

Endpoints

All operations are REST endpoints under the base URL. The send path is the most common:

Full per-resource endpoint listings (conversations, contacts, webhooks, API keys, organizations) live in the API reference.

Request body

POST /v1/messages accepts a JSON body with a channel discriminator and channel content nested under a matching key. For email, content is nested under email.

{
  "to": [{ "email": "ada@example.com" }],
  "channel": "email",
  "email": {
    "subject": "Welcome to Samva",
    "html": "<h1>Welcome!</h1>",
    "text": "Welcome!"
  }
}

to field

to is an array. Each entry is one of:

Both forms resolve to the same POST /v1/messages endpoint.

email object

Response format

Success

A successful POST /v1/messages returns 201 with the created message object. A newly accepted send starts in pending status. The full object carries many more fields (recipients, deliveries, metadata); the most relevant are shown here:

{
  "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "status": "pending",
  "channel": "email",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

See the API reference for the complete response schema.

Error

Errors are returned as a flat JSON object. A _tag field carries the machine-readable discriminator, and the remaining fields are specific to that error type. There is no wrapper object — the error fields sit at the top level of the response body.

A validation failure (422):

{
  "_tag": "ValidationError",
  "message": "Invalid request body",
  "fields": {
    "to": ["Must be a valid email address"]
  }
}

The _tag value maps to the HTTP status code:

For example, a missing resource (404):

{
  "_tag": "ResourceNotFoundError",
  "resource": "Message",
  "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f"
}

A rate-limit response (429):

{
  "_tag": "RateLimitedError",
  "retryAfterSeconds": 30
}

For the authoritative list of error types and their fields, see the OpenAPI specification.

HTTP status codes

Rate limiting

Requests are rate-limited per organization. When a limit is exceeded, the API returns 429 Too Many Requests with a RateLimitedError body. Its retryAfterSeconds field tells you how long to wait before retrying.

{
  "_tag": "RateLimitedError",
  "retryAfterSeconds": 30
}

Back off for retryAfterSeconds and retry.

Pagination

List endpoints accept page and limit query parameters.

GET /v1/messages?page=2&limit=50

Paginated responses include a pagination object.

{
  "data": [],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 245,
    "totalPages": 5
  }
}

Idempotency

Samva automatically deduplicates identical sends: a message with the same recipient and content submitted again within a short window resolves to the original message instead of sending twice. You don't need to supply an idempotency key.

OpenAPI specification

The live machine-readable specification is published at api.samva.app/v1/openapi.json. See the OpenAPI reference for details.

Related