Quickstart

This guide will walk you through sending your first notification with Zyphr in under 5 minutes.

Prerequisites

• A Zyphr account (Sign up free)
• An API key (created in the Dashboard)

Using an AI coding editor?

Skip the SDK install and code snippets — drop the Zyphr MCP Server into Claude Code, Cursor, Cline, or any MCP-compatible client. Once it's connected, ask the AI "add Zyphr email to this project" and it will wire up the install, the client, the route, and even the webhook signature verification for you.

Step 1: Create an Account

1. Go to app.zyphr.dev/signup
2. Create your account with email/password or OAuth
3. An account and a Default project are created automatically — you are ready to go

Accounts & Projects

Your account is your organization — it owns billing, team members, and projects. A project is an isolated environment with its own API keys, domains, subscribers, and messages. You can create additional projects later (e.g., Production, Staging, Development). See Accounts & Projects for details.

Step 2: Get Your API Key

All resources — including API keys — are created within your current project. Make sure you are in the correct project before proceeding (use the project switcher in the header).

1. Navigate to Settings > API Keys in the dashboard
2. Click Create API Key
3. Give it a name (e.g., "Development")
4. Copy your API key — you will only see it once!

Test Mode

Use zy_test_* prefixed keys during development. Test mode messages are stored but never delivered to actual recipients.

Step 3: Send Your First Email

cURL

curl -X POST https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@example.com",
    "subject": "Hello from Zyphr!",
    "html": "<h1>It works!</h1><p>You just sent your first email with Zyphr.</p>"
  }'

Node.js

import { Configuration, EmailsApi } from '@zyphr-dev/node-sdk';

const config = new Configuration({ apiKey: 'zy_test_your_api_key' });
const emails = new EmailsApi(config);

const result = await emails.sendEmail({
  sendEmailRequest: {
    to: 'test@example.com',
    subject: 'Hello from Zyphr!',
    html: '<h1>It works!</h1><p>You just sent your first email with Zyphr.</p>',
  },
});

console.log(`Email sent: ${result.id}`);

Python

import requests

response = requests.post(
    "https://api.zyphr.dev/v1/emails",
    headers={
        "X-API-Key": "zy_test_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "to": "test@example.com",
        "subject": "Hello from Zyphr!",
        "html": "<h1>It works!</h1><p>You just sent your first email with Zyphr.</p>",
    },
)

data = response.json()
print(f"Email sent: {data['data']['id']}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "to":      "test@example.com",
        "subject": "Hello from Zyphr!",
        "html":    "<h1>It works!</h1><p>You just sent your first email with Zyphr.</p>",
    })

    req, _ := http.NewRequest("POST", "https://api.zyphr.dev/v1/emails", bytes.NewBuffer(body))
    req.Header.Set("X-API-Key", "zy_test_your_api_key")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Printf("Status: %d\n", resp.StatusCode)
}

PHP

<?php

$ch = curl_init('https://api.zyphr.dev/v1/emails');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: zy_test_your_api_key',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => 'test@example.com',
        'subject' => 'Hello from Zyphr!',
        'html' => '<h1>It works!</h1><p>You just sent your first email with Zyphr.</p>',
    ]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Email sent: " . $data['data']['id'] . "\n";

curl_close($ch);

Ruby

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.zyphr.dev/v1/emails')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['X-API-Key'] = 'zy_test_your_api_key'
request['Content-Type'] = 'application/json'
request.body = {
  to: 'test@example.com',
  subject: 'Hello from Zyphr!',
  html: '<h1>It works!</h1><p>You just sent your first email with Zyphr.</p>'
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts "Email sent: #{data['data']['id']}"

Response:

{
  "data": {
    "id": "msg_abc123",
    "to": "test@example.com",
    "subject": "Hello from Zyphr!",
    "status": "queued",
    "is_test": true,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

Send a test email before verifying a domain

You don't have to verify a domain just to see Zyphr work. From the dashboard, the Send test email card delivers a real email to your own verified account address, sent from an isolated Zyphr sandbox sender — no domain setup required. It's the fastest way to confirm your account is live before you wire up production sending.

• The recipient is always your own signed-in, email-verified account address — you can't send a sandbox test to anyone else.
• It's a dashboard onboarding aid (available with your dashboard session), limited to a few sends per day. For sending to real recipients, verify a domain and use the Emails API with an API key.

Step 4: Verify Domain (for Production)

Before sending production emails to real recipients, you need to verify your domain:

1. Go to Settings → Domains
2. Click Add Domain
3. Enter your domain (e.g., notifications.yourapp.com)
4. Add the DNS records shown to your DNS provider
5. Click Verify once records are propagated

Step 5: Go Live

Once your domain is verified, swap your test key for a live key:

curl -X POST https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "real-user@example.com",
    "from": "hello@notifications.yourapp.com",
    "subject": "Welcome!",
    "html": "<h1>Welcome to our app!</h1>"
  }'

Next Steps

• Learn about Authentication
• Explore Test Mode
• Send Push Notifications
• Browse the API Reference