SimplyStack Documentation

Overview

The Email & CRM API provides comprehensive email functionality including configuration management, transactional email sending, and lead management with built-in CRM capabilities. Send beautiful emails using templates and track your leads through the sales pipeline.

✨ Key Features

• Transactional email sending
• Built-in email templates (welcome, lead_captured)
• Custom template support with variables
• Lead management & CRM functionality
• Email analytics & delivery tracking
• Automatic domain configuration

Authentication

All email endpoints require authentication via the x-api-key header. Email operations are automatically scoped to your project.

curl -H "x-api-key: your_api_key_here" \
     -H "Content-Type: application/json" \
     https://www.simplystack.dev/api/v1/emails

Email Configuration

Setup Email Configuration

POST/api/v1/emails/setup

Initialize email configuration for your project. Creates subdomain and sets up sending limits.

Request Body

{
  "fromName": "Your Company Name"
}

Example Response

{
  "data": {
    "id": "config_123",
    "project_id": "proj_456",
    "subdomain": "your-project-subdomain",
    "from_name": "Your Company Name",
    "from_email": "your-project-subdomain@simplystack.dev",
    "daily_limit": 100,
    "monthly_limit": 3000,
    "is_verified": true,
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Get Email Configuration

GET/api/v1/emails/setup

Retrieve current email configuration for your project.

Sending Emails

Send Email

POST/api/v1/emails/send

Send a transactional email with HTML content or templates.

Request Body (HTML Email)

{
  "to": "user@example.com",
  "subject": "Welcome to our service",
  "html": "<h1>Welcome!</h1><p>Thank you for signing up!</p>"
}

Request Body (Template Email)

{
  "to": "user@example.com",
  "template": "welcome",
  "templateData": {
    "app_name": "Your App Name",
    "name": "John Doe"
  }
  // Subject auto-generated: "Welcome to Your App Name!"
}

Available Templates

welcome - Requires: app_name, name
lead_captured - Requires: app_name, email, name, source, timestamp

Example Response

{
  "data": {
    "id": "email_789",
    "to_email": "user@example.com",
    "from_email": "your-subdomain@simplystack.dev",
    "subject": "Welcome to our service",
    "status": "sent",
    "resend_email_id": "re_abcd1234",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Lead Management

Create Lead

POST/api/v1/emails/leads

Create a new lead with optional welcome email.

Request Body

{
  "email": "lead@example.com",
  "name": "Jane Smith",
  "source": "landing_page",
  "sendWelcomeEmail": true,
  "welcomeTemplate": "welcome",
  "welcomeSubject": "Welcome to our newsletter!",
  "metadata": {
    "campaign": "summer_2024",
    "interest": "web_development"
  }
}

Example Response

{
  "data": {
    "leadId": "lead_123",
    "lead": {
      "id": "lead_123",
      "email": "lead@example.com",
      "name": "Jane Smith",
      "status": "new",
      "source": "landing_page",
      "created_at": "2024-01-15T10:00:00Z"
    },
    "welcomeEmail": {
      "success": true,
      "emailId": "email_456"
    }
  }
}

List Leads

GET/api/v1/emails/leads

Retrieve leads with optional filtering and pagination.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `new`, `contacted`, `qualified`, `converted`
`source`	string	Filter by lead source
`limit`	number	Number of leads to return (default: 50, max: 100)
`offset`	number	Number of leads to skip (default: 0)

Update Lead

PUT/api/v1/emails/leads/{id}

Update lead information and status.

Request Body

{
  "name": "John Updated",
  "company": "ACME Corporation",
  "phone": "+1-555-0123",
  "status": "contacted",
  "metadata": {
    "notes": "Interested in enterprise plan",
    "last_contact": "2024-01-15"
  }
}

Email Analytics

Get Email Statistics

GET/api/v1/emails/stats

Get comprehensive email and lead statistics for your project.

Example Response

{
  "data": {
    "totalEmails": 1247,
    "totalLeads": 892,
    "configurationStatus": "configured",
    "emailsThisMonth": 156,
    "leadsThisMonth": 89,
    "deliveryRate": 98.5
  }
}

List Sent Emails

GET/api/v1/emails

Retrieve sent emails with pagination support.

SDK Examples

import { SimplyStackSDK } from "@simplystack-org/sdk";

const sdk = new SimplyStackSDK("your-api-key-here");

// Setup email configuration
await sdk.setupEmailConfiguration({
  fromName: "Your Company Name"
});

// Send welcome email
await sdk.sendEmail({
  to: "user@example.com",
  template: "welcome",
  templateData: {
    app_name: "Your App",
    name: "John Doe"
  }
});

// Create lead with welcome email
await sdk.createLead({
  email: "lead@example.com",
  name: "Jane Smith",
  source: "landing_page",
  sendWelcomeEmail: true,
  welcomeTemplate: "welcome"
});

// Get email statistics
const { data: stats } = await sdk.getEmailStats();
console.log(`Sent ${stats.totalEmails} emails to ${stats.totalLeads} leads`);

Error Handling

All email endpoints return consistent error responses. Common error scenarios include:

Common Errors

• Configuration not found: Email configuration must be set up first
• Missing template variables: All required template variables must be provided
• Daily/monthly limit exceeded: Check your sending limits in configuration
• Invalid email format: Ensure email addresses are properly formatted

// Error response example
{
  "error": "Missing required template variables: app_name, name",
  "required_variables": ["app_name", "name"],
  "provided_variables": []
}