User GuideAPI Playground

API Playground

The API Playground is an interactive tool for testing API endpoints without writing code. Perfect for exploring the API, debugging integrations, and learning how endpoints work.

Overview

The API Playground provides a user-friendly interface to:

  • Test all API endpoints interactively
  • View request and response data in real-time
  • Generate code examples automatically
  • Debug API issues quickly
  • Learn API usage through experimentation

Getting Started

Accessing the Playground

  1. Navigate to API → Playground from the main menu
  2. The playground opens with all available endpoints listed

Authentication

The playground automatically uses your account credentials:

  • Logged in: Your session token is used
  • API Key: Optionally use a specific API key for testing

Interface Layout

Left Panel: Endpoint List

Browse all available API endpoints organized by category:

Categories:

  • 🔐 Authentication
  • 📧 Emails
  • 🎨 Templates
  • 📄 Attachments
  • 📊 Analytics
  • 🔑 API Keys
  • 👥 Teams
  • 👤 Users

Each endpoint shows:

  • HTTP method badge (GET, POST, PUT, DELETE)
  • Endpoint path
  • Brief description

Center Panel: Request Builder

Build your API request interactively:

Components:

  1. HTTP Method: GET, POST, PUT, DELETE, PATCH
  2. Endpoint URL: Full URL with path parameters
  3. Headers: Add custom headers
  4. Query Parameters: For GET requests
  5. Request Body: JSON editor for POST/PUT requests

Features:

  • Syntax highlighting for JSON
  • Auto-completion for variables
  • Validation before sending
  • Pretty print formatting

Right Panel: Response Viewer

View the API response after sending a request:

Tabs:

  1. Response: Formatted JSON response
  2. Headers: Response headers
  3. Raw: Raw response text
  4. Code: Auto-generated code examples

Using the Playground

Step 1: Select an Endpoint

Click on any endpoint from the left panel. The center panel updates with:

  • Endpoint URL
  • Required parameters
  • Optional parameters
  • Example request body (if applicable)

Step 2: Fill in Parameters

Path Parameters:

  • Highlighted in blue in the URL
  • Click to edit inline
  • Example: /templates/:id → /templates/123

Query Parameters:

  • Add key-value pairs
  • Toggle to enable/disable
  • Example: limit=10&offset=0

Request Body:

  • JSON editor with syntax highlighting
  • Pre-filled with example data
  • Edit as needed

Step 3: Send Request

Click the Send button to execute the request.

Loading state:

  • Spinner appears
  • “Sending…” indicator
  • Cancel button available

Step 4: View Response

Response appears in the right panel:

Success Response (200-299):

  • Green header bar
  • Status code displayed
  • Response time shown
  • Formatted JSON

Error Response (400-599):

  • Red header bar
  • Error code displayed
  • Error message
  • Detailed error information

Code Generation

The playground automatically generates code examples in multiple languages.

Available Languages

  1. JavaScript/TypeScript - Using fetch or axios
  2. Python - Using requests library
  3. PHP - Using cURL or Guzzle
  4. cURL - Command-line examples
  5. Ruby - Using HTTParty
  6. Go - Using net/http

How to Use

  1. Send a successful request
  2. Click the Code tab in the right panel
  3. Select your preferred language from dropdown
  4. Click Copy to copy the code
  5. Paste into your application

Example Output (JavaScript)

const response = await fetch('https://api.formamail.com/api/emails/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fm_sk_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: ['recipient@example.com'],
    subject: 'Test Email',
    body: {
      type: 'html',
      content: '<h1>Hello!</h1>'
    }
  })
});
 
const data = await response.json();
console.log(data);

Testing Specific Endpoints

Send Email Endpoint

Path: POST /api/emails/send

Test scenario:

  1. Select “Send Email” from Emails category
  2. Fill in recipient email
  3. Enter subject line
  4. Add email body (HTML or plain text)
  5. Optionally add attachments
  6. Click Send

Expected response:

{
  "id": "email_abc123",
  "status": "queued",
  "message": "Email queued for sending"
}

Get Templates Endpoint

Path: GET /api/templates

Test scenario:

  1. Select “List Templates” from Templates category
  2. Add query parameters (limit, offset)
  3. Click Send

Expected response:

{
  "data": [
    {
      "id": "tmpl_123",
      "name": "Welcome Email",
      "type": "email",
      "status": "published"
    }
  ],
  "total": 10,
  "hasMore": true
}

Playground Features

Request History

View your recent API requests:

  • Located in bottom-left corner
  • Shows last 10 requests
  • Click to restore request
  • Clear history option

Save Requests

Save frequently used requests:

  • Click “Save” button
  • Give it a name
  • Appears in “Saved” tab
  • Load anytime with one click

Environment Variables

Define reusable variables:

  • Click “Environment” button
  • Add key-value pairs
  • Use in requests: {{variableName}}
  • Example: {{baseUrl}}/api/emails

Common variables:

  • baseUrl
  • apiKey
  • templateId
  • testEmail

Share Requests

Share API requests with team members:

  • Click “Share” button
  • Generates unique link
  • Team members can view and execute
  • Permissions controlled by workspace

Tips and Tricks

Test with Real Data

Use actual data from your account:

  • Real template IDs
  • Valid email addresses
  • Existing variable names

Check Error Messages

If request fails:

  • Read error message carefully
  • Check status code
  • Review request body format
  • Verify authentication

Use Query Parameters

For GET requests, leverage query parameters:

  • limit - Control result count
  • offset - Implement pagination
  • sort - Sort results
  • filter - Filter by status

Validate JSON

Before sending POST/PUT requests:

  • Use JSON validator
  • Check for syntax errors
  • Ensure proper formatting
  • Verify required fields

Common Use Cases

1. Testing Template Rendering

Send a test email using a template:

  1. Select “Send Email” endpoint
  2. Choose template via templateId
  3. Provide variable values
  4. Send to test email address

2. Debugging API Integration

When your integration fails:

  1. Recreate the request in playground
  2. Send and check response
  3. Compare with your code
  4. Fix issues in your integration

3. Learning API Behavior

Explore what each endpoint does:

  1. Browse all endpoints
  2. Try different parameters
  3. Observe responses
  4. Understand data structures

4. Generating Code Samples

Get code for your application:

  1. Build request in playground
  2. Send successfully
  3. Switch to Code tab
  4. Copy code in your language

Keyboard Shortcuts

  • Ctrl/Cmd + Enter - Send request
  • Ctrl/Cmd + K - Clear request
  • Ctrl/Cmd + S - Save request
  • Ctrl/Cmd + H - View history
  • Esc - Close modals

Common Questions

Can I use the playground to send production emails?

Yes, but it’s not recommended. Use the playground for testing, then integrate via code for production.

Are playground requests logged?

Yes, all requests are logged in Email Logs (for email sends) or audit logs (for other operations).

Can I test with different API keys?

Yes, add a custom Authorization header with your API key in the Headers section.

Why am I getting authentication errors?

Ensure you’re logged in or have provided a valid API key in the Authorization header.

What’s Next?

Need help? Contact support@formamail.com or check our FAQ

AnalyticsAPI Keys