Popup Forms

Create and manage popup forms to capture leads on any website with customizable triggers and designs.

Overview

Popup forms allow you to:

• Create embeddable popup forms for any website
• Configure trigger conditions (on load, exit intent, after delay)
• Connect directly to email lists
• Track views and conversion rates
• Embed with a simple JavaScript snippet

List All Popup Forms

Get all popup forms for your account.

GET /api/popup-forms

Response

[
  {
    "id": "pf_123",
    "name": "Newsletter Popup",
    "list_id": "list_456",
    "list_name": "Newsletter Subscribers",
    "trigger_type": "exit_intent",
    "trigger_delay_ms": null,
    "is_published": true,
    "views": 5420,
    "submissions": 234,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-20T14:30:00Z"
  }
]

Get Single Popup Form

Get details for a specific popup form.

GET /api/popup-forms/:id

Response

{
  "id": "pf_123",
  "name": "Newsletter Popup",
  "list_id": "list_456",
  "list_name": "Newsletter Subscribers",
  "trigger_type": "exit_intent",
  "trigger_delay_ms": null,
  "html": "<div>...</div>",
  "css": "body { ... }",
  "is_published": true,
  "views": 5420,
  "submissions": 234,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z"
}

Create Popup Form

Create a new popup form.

POST /api/popup-forms

Request Body

{
  "name": "Exit Intent Popup",
  "list_id": "list_456",
  "trigger_type": "exit_intent"
}

Field Options

Trigger Types

Response

{
  "id": "pf_789",
  "name": "Exit Intent Popup",
  "list_id": "list_456",
  "trigger_type": "exit_intent",
  "trigger_delay_ms": null,
  "is_published": false,
  "views": 0,
  "submissions": 0,
  "created_at": "2024-01-22T09:00:00Z",
  "updated_at": "2024-01-22T09:00:00Z"
}

Update Popup Form Settings

Update popup form settings (name, list, trigger).

POST /api/popup-forms/:id/save-settings

Request Body

{
  "name": "Updated Popup",
  "list_id": "list_456",
  "trigger_type": "after_delay",
  "trigger_delay_ms": 5000
}

Response

{
  "id": "pf_123",
  "name": "Updated Popup",
  "list_id": "list_456",
  "trigger_type": "after_delay",
  "trigger_delay_ms": 5000,
  "updated_at": "2024-01-22T11:00:00Z"
}

Update Popup Form Design

Save the HTML and CSS for a popup form.

POST /api/popup-forms/:id/save-design

Request Body

{
  "html": "<div class=\"popup\">...</div>",
  "css": ".popup { max-width: 500px; }"
}

Response

{
  "success": true,
  "message": "Design saved successfully"
}

Publish/Unpublish Popup Form

Toggle the published state of a popup form.

POST /api/popup-forms/:id/publish

Request Body

{
  "is_published": true
}

Parameters

Response

{
  "id": "pf_123",
  "is_published": true,
  "updated_at": "2024-01-22T12:00:00Z"
}

Duplicate Popup Form

Create a copy of an existing popup form.

POST /api/popup-forms/:id/duplicate

Response

{
  "id": "pf_999",
  "name": "Newsletter Popup (Copy)",
  "list_id": "list_456",
  "trigger_type": "exit_intent",
  "html": "<div>...</div>",
  "css": "body { ... }",
  "is_published": false,
  "created_at": "2024-01-22T13:00:00Z"
}

Delete Popup Form

Delete a popup form permanently.

DELETE /api/popup-forms/:id

Response

{
  "success": true,
  "message": "Popup form deleted successfully"
}

Embedding Popup Forms

JavaScript Snippet

Once published, embed the popup on your website using this script:

<script 
  src="https://cdn.postbeagle.com/popup.js" 
  data-popup-id="pf_123"
  defer
></script>

Add this script just before the closing </body> tag.

Customization Options

<script 
  src="https://cdn.postbeagle.com/popup.js" 
  data-popup-id="pf_123"
  data-test-mode="true"
  data-show-once="true"
  defer
></script>

Form Integration

Popup forms automatically handle submissions when forms include the data-pb-form="subscribe" attribute.

Required Form Structure

<form data-pb-form="subscribe">
  <input type="email" name="email" required />
  <input type="text" name="first_name" />
  <button type="submit" data-pb-submit>Subscribe</button>
  <div data-pb-message></div>
</form>

Standard Fields

• email - Email address (required)
• first_name - First name
• last_name - Last name
• phone - Phone number

Custom Fields

Any additional form fields are captured as custom fields:

<input type="text" name="company" />
<input type="text" name="interests" />

Code Examples

Create and Publish a Popup

const apiKey = 'your_api_key';
const baseUrl = 'https://api.postbeagle.com/api';

// 1. Create popup form
const createResponse = await fetch(`${baseUrl}/popup-forms`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Exit Intent Newsletter',
    list_id: 'list_123',
    trigger_type: 'exit_intent'
  })
});

const popup = await createResponse.json();
const popupId = popup.id;

// 2. Save design
await fetch(`${baseUrl}/popup-forms/${popupId}/save-design`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    html: `
      <div style="max-width: 400px; padding: 30px; background: white; border-radius: 10px;">
        <h2>Don't Miss Out!</h2>
        <p>Subscribe to get weekly updates</p>
        <form data-pb-form="subscribe">
          <input type="email" name="email" placeholder="Your email" required />
          <button type="submit" data-pb-submit>Subscribe</button>
          <div data-pb-message></div>
        </form>
      </div>
    `,
    css: 'h2 { margin: 0 0 15px; }'
  })
});

// 3. Publish
await fetch(`${baseUrl}/popup-forms/${popupId}/publish`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    is_published: true
  })
});

console.log(`Popup ready! Embed with data-popup-id="${popupId}"`);

Get Popup Performance Metrics

import requests

api_key = 'your_api_key'
base_url = 'https://api.postbeagle.com/api'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Get all popup forms
response = requests.get(f'{base_url}/popup-forms', headers=headers)
popups = response.json()

# Calculate performance
for popup in popups:
    views = popup['views']
    submissions = popup['submissions']
    conversion_rate = (submissions / views * 100) if views > 0 else 0
    
    print(f"{popup['name']}:")
    print(f"  Views: {views}")
    print(f"  Submissions: {submissions}")
    print(f"  Conversion Rate: {conversion_rate:.2f}%")
    print(f"  Trigger: {popup['trigger_type']}")
    print()

Create Time-Delayed Popup

// Create popup that shows after 10 seconds
const response = await fetch('https://api.postbeagle.com/api/popup-forms', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '10 Second Delay Popup',
    list_id: 'list_123',
    trigger_type: 'after_delay',
    trigger_delay_ms: 10000
  })
});

Trigger Types Explained

On Load

Shows immediately when the page loads. Best for:

• High-priority announcements
• Limited time offers
• Critical information

{
  "trigger_type": "on_load"
}

Exit Intent

Shows when user moves mouse toward browser top (intent to leave). Best for:

• Reducing bounce rate
• Last-chance offers
• Newsletter signups

{
  "trigger_type": "exit_intent"
}

After Delay

Shows after a specified delay. Best for:

• Engaged visitors
• Content consumption
• Non-intrusive capture

{
  "trigger_type": "after_delay",
  "trigger_delay_ms": 30000
}

Best Practices

1. Right Trigger: Choose trigger type based on user behavior
2. Clear Value: Communicate what users get by subscribing
3. Minimal Fields: Request only essential information
4. Easy Close: Always provide clear way to close popup
5. Mobile Friendly: Ensure design works on all devices
6. A/B Testing: Test different designs and triggers
7. Frequency Capping: Use data-show-once="true" to avoid annoying users
8. Fast Load: Keep designs lightweight

Analytics Tracking

Popup forms automatically track:

• Views: Number of times popup was displayed
• Submissions: Successful form submissions
• Conversion Rate: Submissions / Views
• Trigger Performance: Compare effectiveness of different triggers

Error Codes

Testing

Use test mode to preview without tracking:

<script 
  src="https://cdn.postbeagle.com/popup.js" 
  data-popup-id="pf_123"
  data-test-mode="true"
  defer
></script>

Test mode:

• Shows popup normally
• Doesn't increment view count
• Doesn't track submissions
• Perfect for development/staging

Related Endpoints

• Email Lists - Manage email lists for form submissions
• Landing Pages - Alternative lead capture pages
• Contacts - View captured leads
• Analytics - Detailed performance metrics