SendPromptly API Documentation

The SendPromptly API provides endpoints for managing subscribers and automating email campaigns with advanced scheduling features.

Base URL: https://app.sendpromptly.com

Authentication

All API endpoints require authentication using query parameters only (not headers):

  • Use prj_api_key for project-level endpoints (e.g., campaigns, subscribers)
  • Use msg_api_key for email-message-level endpoints (e.g., transactional sends, email message management)

⚠️ Important: API keys must be sent as query parameters, not as headers like X-API-Key.

You can find your API keys in your SendPromptly under

  • Project → Messages → API Key.
  • Send → Messages → API Key.

Example Usage

  • Project-level: /api/subscribers?prj_api_key=your-project-api-key
  • Email message-level: /api/email-messages?msg_api_key=your-email-message-api-key
  • Email message-level: /api/email-messages?msg_api_key=your-email-message-api-key

Email Scheduling

SendPromptly’s unique email scheduling feature allows you to automatically send emails when subscribers are added:

  • delay_value (integer, default: 0) - Delay in hours before sending

Custom Subscriber Fields

SendPromptly supports custom fields for storing additional subscriber data:

  • ✅ Field names only: Use descriptive names like "company", "position", "ip_address"
  • ❌ No field IDs: Numeric identifiers are not supported
  • 🔒 Strict validation: Only predefined field names are accepted
  • 📝 String values: Maximum 255 characters per field

Example:

{
  "subscriber_fields": {
    "company": "Tech Corp",
    "position": "Developer"
  }
}

Contact Form Notifications

SendPromptly automatically sends email notifications to project owners when new contact form submissions are received:

  • 🔄 Automatic: No additional configuration required
  • 📧 Instant notifications: Project owners receive immediate email alerts for new submissions
  • 📊 Full tracking: All notifications are logged in SendLog with contact_notification type
  • 🎯 Smart categorization: Contact notifications are separate from regular subscriber emails

Key Features:

  • Contact form data is captured as subscriber fields (message, source_page, ip_address, etc.)
  • Project owner gets notified via email with submission details
  • Notifications use system templates for consistent formatting
  • Failed notifications don’t prevent subscriber creation
  • Full audit trail in SendLog for analytics

Example contact form submission:

{
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith",
  "subscriber_fields": {
    "message": "Interested in your premium plan pricing",
    "source_page": "https://yoursite.com/contact",
    "ip_address": "203.0.113.45",
    "subject": "Pricing Inquiry"
  }
}

Quick Start

1. Create a Subscriber with Email Scheduling

curl -X POST https://app.sendpromptly.com/api/subscribers \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "delay_value": 24
  }' \
  "?prj_api_key=your-project-api-key"

2. List Subscribers

curl -X GET "https://app.sendpromptly.com/api/subscribers?prj_api_key=your-project-api-key"

API Endpoints

Response Format

All API responses follow this consistent format:

Success Response:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { /* resource data */ }
}

Error Response:

{
  "success": false,
  "message": "Error description",
  "errors": { /* validation errors if applicable */ }
}

Rate Limits

API rate limits are based on your subscription plan:

  • Free Plan: 60 requests per minute
  • Standard Plan: 300 requests per minute
  • Premium Plan: 600 requests per minute

Rate limit headers are included in each response:

X-RateLimit-Limit: <max requests per minute>
X-RateLimit-Remaining: <requests remaining in current window>
X-RateLimit-Reset: <seconds until window resets, only when limit is reached>

For detailed information about rate limiting, please see our Rate Limiting Documentation.

Additional limits:

  • Bulk operations: Maximum 1000 records per request

Need Help?