Send your first email

Welcome to Samva. In this tutorial you'll send a real email from start to finish: get an API key, install the SDK, send one email, and confirm it went out. No prior setup required beyond a Samva account and Node.js.

By the end you'll have sent your first email and seen its delivery status. Let's go.

Before you start

Make sure you have:

• A Samva account — sign up at samva.app/dashboard.
• Node.js 18 or newer installed.

That's everything. Follow each step in order.

Step 1: Get your API key

1. Log in to your Samva dashboard.
2. Open Developers → API Keys.
3. Click Create API Key.
4. Copy the key somewhere safe — you'll use it in a moment.

Now make the key available to your code as an environment variable. In your terminal, run this once (it lasts for your current terminal session):

export SAMVA_API_KEY="sk_sm_your_api_key"

Step 2: Install the SDK

In your project directory, install the samva package:

Step 3: Create the client

Create a file called send.ts and initialize the Samva client with your API key:

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

The client reads SAMVA_API_KEY from the environment variable you set in Step 1, so the key never appears in your code.

Step 4: Send your first email

Add the send call to send.ts. Pass the recipient address as a string, a subject, and an HTML body. Replace ada@example.com with an address you can check:

import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const result = await samva.email.send({
  to: "ada@example.com",
  subject: "Welcome to Samva",
  html: "<h1>Welcome!</h1><p>Thanks for joining.</p>",
});

console.log("Email sent:", result.data?.id);

Now run it. The samva SDK is TypeScript-first, so run the file with tsx — npx fetches it on the fly, no install needed:

npx tsx send.ts

You should see output like Email sent: 7c9e6679-7425-40de-944b-e07fc1f90ae7. That id is the message you just created — hold onto it for the next step.

Step 5: Check that it arrived

Use the message id from Step 4 to look up its delivery status:

const message = await samva.messages.get({
  id: result.data?.id!,
});

console.log("Status:", message.data?.status);

The status moves through pending, processing, sent, and finally delivered once the email reaches the recipient. Check the inbox you sent to — your first Samva email should be waiting there.

What you've done

You just:

• Created a Samva API key and stored it as an environment variable.
• Installed the SDK and initialized the client.
• Sent a real email with samva.email.send.
• Looked up its delivery status.

What's next

Need a hand? Email us at support@samva.app.