SDKs & Tools
REST API
Direct REST API integration guide for Samva
Integrate directly with Samva's REST API using any HTTP client or programming language.
Base URL
https://api.samva.app/v1Authentication
All API requests require authentication via the X-API-Key header:
curl -H "X-API-Key: sk_live_your_api_key" \
https://api.samva.app/v1/messagesContent Type
All requests should include the Content-Type: application/json header for POST/PUT/PATCH requests.
Examples
Send Email
curl -X POST https://api.samva.app/v1/email/send \
-H "X-API-Key: sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"to": "user@example.com",
"subject": "Welcome to Samva",
"html": "<h1>Hello!</h1><p>Welcome to our platform.</p>",
"text": "Hello! Welcome to our platform."
}'Response:
{
"id": "msg_abc123def456",
"status": "pending"
}Send SMS
curl -X POST https://api.samva.app/v1/sms/send \
-H "X-API-Key: sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155552671",
"message": "Your verification code is 123456"
}'Send WhatsApp Message
curl -X POST https://api.samva.app/v1/whatsapp/send \
-H "X-API-Key: sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155552671",
"message": "Hello from Samva!"
}'List Messages
curl https://api.samva.app/v1/messages \
-H "X-API-Key: sk_live_your_api_key"Get Message by ID
curl https://api.samva.app/v1/messages/msg_abc123def456 \
-H "X-API-Key: sk_live_your_api_key"Response Format
All responses follow a consistent JSON format:
Success Response
{
"id": "msg_abc123def456",
"status": "pending",
"channel": "email",
"createdAt": "2024-01-15T10:30:00.000Z"
}Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email address format",
"details": {
"field": "to",
"reason": "Must be a valid email address"
}
}
}HTTP Status Codes
| Code | Description |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request - Invalid parameters |
401 | UnauthorizedError - Invalid or missing API key |
403 | ForbiddenError - Insufficient permissions |
404 | Not Found - Resource doesn't exist |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error |
Rate Limiting
API requests are rate-limited based on your plan. Rate limit information is included in response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200Pagination
List endpoints support pagination via query parameters:
curl "https://api.samva.app/v1/messages?page=1&limit=20" \
-H "X-API-Key: sk_live_your_api_key"Response includes pagination metadata:
{
"items": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
}
}Language Examples
Python (requests)
import requests
headers = {
'X-API-Key': 'sk_live_your_api_key',
'Content-Type': 'application/json'
}
response = requests.post(
'https://api.samva.app/v1/email/send',
headers=headers,
json={
'to': 'user@example.com',
'subject': 'Hello',
'text': 'Welcome to Samva!'
}
)
print(response.json())Go (net/http)
package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
payload := map[string]string{
"to": "user@example.com",
"subject": "Hello",
"text": "Welcome to Samva!",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
"https://api.samva.app/v1/email/send",
bytes.NewBuffer(body))
req.Header.Set("X-API-Key", "sk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}PHP (cURL)
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.samva.app/v1/email/send',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: sk_live_your_api_key',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
'to' => 'user@example.com',
'subject' => 'Hello',
'text' => 'Welcome to Samva!'
])
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));