API Documentation

Getting Started

Welcome to SMTP Riser! This comprehensive guide will help you set up and use all the features of our email management platform.

What is SMTP Riser?

SMTP Riser is a powerful email management platform that allows you to:

• Send transactional emails via SMTP
• Create and manage email campaigns
• Build and maintain email lists
• Design email templates
• Set up automated email series
• Monitor email delivery and performance
• Manage multiple SMTP configurations

Quick Setup Guide

Follow these steps to get started:

1. Create an Account

Sign up for a free account at app.smtpriser.com to access the dashboard.

2. Configure SMTP Settings

Navigate to the SMTPs section and add your SMTP server configuration. This is required to send emails.

3. Create Email Templates

Go to Templates to create reusable email templates with variables for personalization.

4. Build Email Lists

Use the Lists section to create and manage your email subscriber lists.

5. Generate API Keys

In the API Keys section, generate keys for programmatic access to the platform.

6. Start Sending

Create campaigns or email series to start sending emails to your lists, or use the API for transactional emails.

Dashboard Overview

The dashboard provides a comprehensive overview of your email activity and performance metrics.

Key Metrics

• Total Emails: All-time email count
• Sent Today: Emails sent in the last 24 hours
• Successfully Sent: Successfully delivered emails
• Failed: Emails that failed to send
• Active Series: Currently running email series
• Total Recipients: Total subscribers across all lists
• Pending: Emails in the sending queue
• Active Campaigns: Currently running campaigns

Daily Activity Chart

The dashboard includes an interactive chart showing daily email activity, including total emails, sent emails, and failed emails over time.

Recent Activity Feed

Monitor recent email activities including successful sends, failures, series completions, and campaign updates in real-time.

Performance Insights

View detailed statistics including success rates, total series, campaigns, lists, and active recipients to track your email marketing performance.

SMTP Configuration

SMTP configurations are essential for sending emails. You can add multiple SMTP servers for redundancy and load distribution.

Adding SMTP Configuration

1. Navigate to the SMTPs section
2. Click New SMTP button
3. Fill in the required information:

Popular SMTP Providers

// Gmail SMTP Configuration
Host: smtp.gmail.com
Port: 587
Secure: true
Username: your-email@gmail.com
Password: your-app-password

// Outlook SMTP Configuration
Host: smtp-mail.outlook.com
Port: 587
Secure: true
Username: your-email@outlook.com
Password: your-password

// SendGrid SMTP Configuration
Host: smtp.sendgrid.net
Port: 587
Secure: true
Username: apikey
Password: your-sendgrid-api-key

Managing SMTP Configurations

• Edit: Update SMTP settings as needed
• Test: Verify SMTP configuration works
• Delete: Remove unused configurations
• Monitor: Track delivery performance per SMTP

Email Templates

Email templates allow you to create reusable email designs with dynamic content using variables.

Creating Templates

1. Navigate to Templates section
2. Click New Email Template
3. Fill in template details:

Template Variables

Use double curly braces to insert dynamic content in your templates:

<h1>Hello {{name}}!</h1>
<p>Welcome to {{company}}</p>
<p>Your order #{{orderNumber}} has been confirmed.</p>
<p>Total: ${{amount}}</p>

<!-- Conditional content -->
{{#if isPremium}}
  <p>Thank you for being a premium member!</p>
{{/if}}

<!-- Loops for lists -->
<ul>
{{#each items}}
  <li>{{this.name}} - ${{this.price}}</li>
{{/each}}
</ul>

Template Management

• Preview: See how templates look with sample data
• Edit: Modify template content and design
• Duplicate: Create variations of existing templates
• Delete: Remove unused templates
• Version Control: Track template changes over time

Best Practices

• Use responsive HTML for mobile compatibility
• Include fallback text for email clients that don't support HTML
• Test templates with different email clients
• Keep subject lines under 50 characters
• Use clear call-to-action buttons
• Include unsubscribe links for compliance

Email Lists Management

Email lists help you organize and manage your subscribers for targeted email campaigns and series.

Creating Email Lists

1. Navigate to Lists section
2. Click New List button
3. Provide list information:

Adding Members to Lists

You can add members to lists in several ways:

1. Manual Addition

1. Open the list you want to manage
2. Click Add Member
3. Enter email address and optional details
4. Click Add to confirm

2. Bulk Import

1. Prepare a CSV file with email addresses
2. Use the Import Members feature
3. Upload your CSV file
4. Map columns to fields (email, firstName, lastName)
5. Review and confirm import

3. API Integration

// Add member to list via API
POST /email-lists/{listId}/members
Content-Type: application/json
Authorization: Bearer {your-token}

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

List Management Features

• Member Count: Track total and active members
• Unsubscribe Tracking: Monitor unsubscribed members
• Member Details: View individual member information
• Export: Download member lists as CSV
• Segmentation: Create segments based on member data
• Cleanup: Remove invalid or bounced email addresses

List Statistics

Each list displays important metrics:

• Total Members: All email addresses in the list
• Active Members: Valid, deliverable email addresses
• Unsubscribed: Members who opted out
• Bounced: Invalid or undeliverable addresses

Email Campaigns

Email campaigns allow you to send one-time emails to your email lists with advanced scheduling and rate limiting options.

Creating Campaigns

1. Navigate to Campaigns section
2. Click New Campaign button
3. Configure campaign settings:

Rate Limiting

Configure sending speed to avoid overwhelming your SMTP server or hitting provider limits:

Campaign Status

Campaigns can have different statuses:

• Draft: Campaign created but not started
• Scheduled: Campaign scheduled for future sending
• Running: Campaign is currently sending emails
• Paused: Campaign temporarily stopped
• Completed: All emails have been sent
• Stopped: Campaign manually stopped

Campaign Management

• Start: Begin sending emails immediately
• Pause: Temporarily stop sending
• Resume: Continue from where you paused
• Stop: Permanently stop the campaign
• Duplicate: Create a copy of the campaign
• Delete: Remove the campaign

Campaign Analytics

Track campaign performance with detailed metrics:

• Total Recipients: Number of people in target list
• Emails Sent: Successfully sent emails
• Emails Failed: Failed delivery attempts
• Success Rate: Percentage of successful sends
• Delivery Time: Average time to deliver emails

Email Series

Email series allow you to create automated, sequential email campaigns where different emails are sent to recipients over time with configurable delays.

Creating Email Series

1. Navigate to Series section
2. Click Create Series button
3. Configure series settings:

Adding Emails to Series

After creating a series, you can add multiple emails with configurable delays:

Adding Recipients

Add recipients to your series who will receive the complete email sequence:

Individual Addition

1. Go to the Recipients tab
2. Click Add Recipient
3. Enter email address
4. Click Add to confirm

Bulk Import

1. Prepare a CSV file with email addresses
2. Use the Import Recipients feature
3. Upload your CSV file
4. Review and confirm import

Series Management

• Start: Begin the email series
• Pause: Temporarily stop the series
• Resume: Continue the series
• Stop: Permanently stop the series
• Duplicate: Create a copy of the series
• Delete: Remove the series

Series Monitoring

Track series progress with comprehensive analytics:

Overview Tab

• Series Status: Current state of the series
• Total Recipients: Number of people in the series
• Emails Sent: Total emails delivered
• Success Rate: Percentage of successful sends
• Progress: Overall completion percentage

Recipients Tab

• Individual Progress: Track each recipient's progress
• Email Count: Number of emails sent to each recipient
• Last Email: Most recent email sent
• Status: Active, completed, or failed

Emails Tab

• Email Sequence: View all emails in order
• Edit Emails: Modify email content and timing
• Reorder: Change the sequence of emails
• Remove: Delete emails from the series

Logs Tab

• Delivery Logs: Detailed sending history
• Status Filtering: Filter by sent, failed, pending
• Error Details: Information about failed sends
• Timestamps: When each email was sent

Use Cases

Email series are perfect for:

• Welcome Sequences: Onboard new users
• Educational Content: Deliver course materials over time
• Product Launches: Build anticipation with teasers
• Re-engagement: Win back inactive users
• Nurturing: Guide prospects through sales funnel
• Event Follow-ups: Post-event communication

API Keys Management

API keys provide secure access to SMTP Riser's RESTful API for programmatic email sending and management.

Generating API Keys

1. Navigate to API Keys section
2. Click Generate New Key
3. Provide key information:

API Key Permissions

• Read Only: View data only, no modifications
• Send Emails: Send emails via API
• Manage Lists: Create and manage email lists
• Manage Templates: Create and manage templates
• Full Access: Complete platform access

Using API Keys

Include your API key in the request headers:

// JavaScript example
const headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'your-api-key-here'
};

// cURL example
curl -X POST https://api.smtpriser.com/api/smtp/send-transaction-email \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "email": "user@example.com",
    "subject": "Hello World",
    "templateId": "welcome-template",
    "smtpConfigId": "your-smtp-config-id"
  }'

API Key Management

• View: See key details and usage statistics
• Regenerate: Create a new key (invalidates old one)
• Revoke: Disable the key immediately
• Delete: Permanently remove the key
• Usage Tracking: Monitor API calls and limits

Security Best Practices

• Store API keys securely (environment variables, secret managers)
• Never commit API keys to version control
• Use different keys for different environments (dev, staging, prod)
• Regularly rotate API keys
• Monitor API key usage for suspicious activity
• Use least privilege principle (minimum required permissions)

Transaction Monitoring

The transaction monitoring system provides detailed insights into email delivery, performance, and system health.

Transaction Overview

Navigate to Transactions to view comprehensive email delivery data:

• Email Status: Sent, failed, pending, or bounced
• Delivery Time: When emails were sent
• Recipient Information: Email addresses and details
• SMTP Server: Which SMTP configuration was used
• Error Messages: Details about failed deliveries
• Campaign/Series: Associated campaign or series

Filtering and Search

Use advanced filters to find specific transactions:

Performance Metrics

Monitor key performance indicators:

• Delivery Rate: Percentage of successfully delivered emails
• Bounce Rate: Percentage of bounced emails
• Average Delivery Time: Time from send to delivery
• SMTP Performance: Performance by SMTP server
• Peak Hours: When most emails are sent
• Error Patterns: Common failure reasons

Error Analysis

Investigate failed deliveries with detailed error information:

Export and Reporting

• CSV Export: Download transaction data for analysis
• PDF Reports: Generate formatted reports
• Scheduled Reports: Automatic report delivery
• Custom Metrics: Create custom performance dashboards

Real-time Monitoring

Stay informed with real-time updates:

• Live Dashboard: Real-time transaction updates
• Alerts: Notifications for high failure rates
• Webhooks: Real-time event notifications
• Status Page: System health monitoring

Troubleshooting Guide

Common issues and solutions:

High Failure Rate

1. Check SMTP configuration and credentials
2. Verify email list quality (remove invalid addresses)
3. Review email content for spam triggers
4. Check SMTP provider status and limits

Slow Delivery

1. Adjust rate limiting settings
2. Check SMTP server performance
3. Consider using multiple SMTP servers
4. Monitor network connectivity

Authentication Issues

1. Verify SMTP credentials
2. Check if 2FA is enabled (use app passwords)
3. Ensure SMTP server supports your authentication method
4. Test SMTP configuration manually

API Reference

SMTP Riser provides a comprehensive RESTful API for programmatic access to all platform features.

Authentication

All API requests require authentication using your API key. Include your API key in the request headers.

Headers

Send Email

Send transactional emails using our RESTful API. You can send simple text emails or use our template system for rich HTML emails.

Request Parameters

Response

{
  "id": "email_123456789",
  "status": "sent",
  "message": "Email queued for delivery",
  "timestamp": "2025-01-27T10:30:00Z"
}

Templates

Create beautiful, responsive email templates using our drag-and-drop builder or upload your own HTML templates.

Template Variables

Use variables in your templates to personalize emails. Variables are passed in the variables object when sending emails.

// Template HTML
<h1>Hello {{name}}!</h1>
<p>Welcome to {{company}}</p>

// Variables object
{
  "variables": {
    "name": "John Doe",
    "company": "Your Company"
  }
}

Error Handling

Our API uses standard HTTP status codes to indicate success or failure of requests.

Common Error Codes

Error Response Format

{
  "error": {
    "code": "invalid_email",
    "message": "Invalid email address format",
    "details": "The email address 'invalid-email' is not valid"
  }
}

SMTP Configuration Examples

Here are common SMTP server configurations for popular email providers. Use these settings when configuring your SMTP credentials in the dashboard.

Gmail SMTP Settings

SMTP Server: smtp.gmail.com
Port: 587 (TLS) or 465 (SSL)
Security: STARTTLS or SSL/TLS
Username: your-email@gmail.com
Password: Your Gmail App Password (not your regular password)

Note: Enable 2-factor authentication and generate an App Password
for SMTP access. Regular Gmail passwords won't work.

Yahoo Mail SMTP Settings

SMTP Server: smtp.mail.yahoo.com
Port: 587 (TLS) or 465 (SSL)
Security: STARTTLS or SSL/TLS
Username: your-email@yahoo.com
Password: Your Yahoo App Password

Note: Generate an App Password in your Yahoo account settings
under "Account Security" > "Generate and manage app passwords".

Outlook/Hotmail SMTP Settings

SMTP Server: smtp-mail.outlook.com
Port: 587
Security: STARTTLS
Username: your-email@outlook.com
Password: Your Outlook password

Note: For Outlook.com accounts, use your regular password.
For Office 365 accounts, you may need to use OAuth2 authentication.

Apple iCloud SMTP Settings

SMTP Server: smtp.mail.me.com
Port: 587 (TLS) or 465 (SSL)
Security: STARTTLS or SSL/TLS
Username: your-email@icloud.com
Password: Your iCloud App Password

Note: Enable 2-factor authentication and generate an App Password
in your Apple ID account settings.

Custom SMTP Server

SMTP Server: mail.yourdomain.com
Port: 587 (TLS) or 465 (SSL) or 25 (non-encrypted)
Security: STARTTLS, SSL/TLS, or None
Username: your-email@yourdomain.com
Password: Your email account password

Note: Contact your hosting provider or IT administrator
for the correct SMTP settings for your domain.

Popular Email Hosting Providers

GoDaddy

SMTP Server: smtpout.secureserver.net
Port: 465 (SSL) or 587 (TLS)
Security: SSL/TLS or STARTTLS
Username: your-email@yourdomain.com
Password: Your email password

Namecheap

SMTP Server: mail.privateemail.com
Port: 465 (SSL) or 587 (TLS)
Security: SSL/TLS or STARTTLS
Username: your-email@yourdomain.com
Password: Your email password

Bluehost

SMTP Server: mail.yourdomain.com
Port: 465 (SSL) or 587 (TLS)
Security: SSL/TLS or STARTTLS
Username: your-email@yourdomain.com
Password: Your email password

Security Best Practices

• Always use encrypted connections (SSL/TLS or STARTTLS)
• Use App Passwords instead of regular passwords when available
• Enable 2-factor authentication on your email accounts
• Regularly rotate your SMTP passwords
• Monitor your email sending activity for any unauthorized use

Troubleshooting

If you're having trouble connecting to your SMTP server:

• Verify your credentials are correct
• Check if your hosting provider blocks SMTP on certain ports
• Ensure your IP address isn't blacklisted
• Try different ports (587, 465, 25)
• Contact your email provider's support for assistance