Quickstart Guide

Get up and running with Samva's email platform in just a few minutes.

In Development: This quickstart guide is being updated as the MVP is built. Some features may not be available yet.

Prerequisites

Before you begin, make sure you have:

A Samva account (sign up at samva.app/signup)
Node.js 18+ installed (for TypeScript SDK)

Step 1: Get Your API Key

Log in to your Samva Dashboard
Navigate to Developers → API Keys
Click Create API Key
Copy your API key and keep it secure

Security Tip: Never commit API keys to version control. Use environment variables instead.

Step 2: Install the SDK

Choose your preferred method:

npm install @samva/sdk

Step 3: Initialize the Client

import { SamvaClient } from '@samva/sdk';

const client = new SamvaClient({
  apiKey: process.env.SAMVA_API_KEY,
  // Optional: Set custom base URL for self-hosted instances
  // baseUrl: 'https://samva.app/api'
});

Step 4: Send Your First Email

// Send transactional email
const emailResponse = await client.messages.send({
  channel: 'email',
  to: 'user@example.com',
  content: {
    subject: 'Welcome to Samva',
    html: '<h1>Welcome!</h1><p>Thanks for joining Samva.</p>',
    from: 'noreply@yourdomain.com'
  }
});

console.log('Email sent:', emailResponse.id);

Step 5: Check Message Status

// Get message status
const status = await client.messages.get(emailResponse.id);

console.log('Delivery status:', status.delivery_status);
// Possible values: queued, sent, delivered, failed, read

// Set up webhook for real-time updates (recommended)
await client.webhooks.create({
  url: 'https://your-app.com/webhooks/samva',
  events: ['message.delivered', 'message.failed'],
  secret: 'your-webhook-secret'
});

Using REST API

If you prefer using the REST API directly:

# Send email via REST API
curl -X POST https://samva.app/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "user@example.com",
    "content": {
      "subject": "Welcome to Samva",
      "html": "<h1>Welcome!</h1><p>Thanks for joining Samva.</p>",
      "from": "noreply@yourdomain.com"
    }
  }'

Next Steps

API Reference

Explore all available endpoints

Authentication

Learn about API keys and security

Email Management

Manage email domains, senders, and templates

Webhooks

Set up real-time event notifications

Common Issues

Invalid Email Address

Error: Invalid email address format

Solution: Ensure the email address is properly formatted (e.g., user@example.com).

Domain Not Verified

Error: Sender domain not verified

Solution: Verify your sending domain in the dashboard under Email → Domains.

Insufficient Credits

Error: Insufficient credits in wallet

Solution: Top up your credits in the Billing Dashboard.

Support

Need help? We're here for you:

📧 Email: support@samva.app
📚 Full Documentation: docs.samva.app
💬 Discord: discord.gg/samva (Coming soon)