ParseBounce/API DocsDashboard

Code Examples

Ready-to-use code examples for common use cases.

Node.js / JavaScript

Check before sending

check-email.js
const API_KEY = process.env.PARSEBOUNCE_API_KEY;
const PROJECT_ID = process.env.PARSEBOUNCE_PROJECT_ID;
const BASE_URL = 'https://api.parsebounce.com';


async function shouldSendEmail(email) {
  const url = `${BASE_URL}/projects/${PROJECT_ID}/suppressions/check?email=${encodeURIComponent(email)}`;


  const response = await fetch(url, {
    headers: { 'X-API-Key': API_KEY }
  });


  if (!response.ok) {
    // On error, default to allowing the email (fail-open)
    console.error('ParseBounce API error:', response.status);
    return true;
  }


  const data = await response.json();
  return !data.suppressed;
}


// Usage
async function sendEmail(to, subject, body) {
  if (await shouldSendEmail(to)) {
    // Send the email via SES, SendGrid, etc.
    console.log('Sending email to:', to);
  } else {
    console.log('Skipping suppressed email:', to);
  }
}

Batch check for bulk sends

batch-check.js
async function filterSuppressedEmails(emails) {
  const url = `${BASE_URL}/projects/${PROJECT_ID}/suppressions/check`;


  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ emails })
  });


  const data = await response.json();


  // Return only non-suppressed emails
  return data.results
    .filter(r => !r.suppressed)
    .map(r => r.email);
}


// Usage
const recipients = ['user1@example.com', 'user2@example.com', 'user3@example.com'];
const validRecipients = await filterSuppressedEmails(recipients);
console.log('Safe to send to:', validRecipients);

Python

Simple check

parsebounce.py
import os
import requests


API_KEY = os.environ.get('PARSEBOUNCE_API_KEY')
PROJECT_ID = os.environ.get('PARSEBOUNCE_PROJECT_ID')
BASE_URL = 'https://api.parsebounce.com'


def is_email_suppressed(email: str) -> bool:
    """Check if an email is in the suppression list."""
    url = f"{BASE_URL}/projects/{PROJECT_ID}/suppressions/check"
    response = requests.get(
        url,
        params={"email": email},
        headers={"X-API-Key": API_KEY}
    )
    response.raise_for_status()
    return response.json().get("suppressed", False)


def filter_suppressed(emails: list[str]) -> list[str]:
    """Filter out suppressed emails from a list."""
    url = f"{BASE_URL}/projects/{PROJECT_ID}/suppressions/check"
    response = requests.post(
        url,
        json={"emails": emails},
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        }
    )
    response.raise_for_status()
    results = response.json()["results"]
    return [r["email"] for r in results if not r["suppressed"]]


# Usage
if not is_email_suppressed("user@example.com"):
    print("Safe to send!")


valid_emails = filter_suppressed(["a@test.com", "b@test.com"])
print(f"Valid emails: {valid_emails}")

Django integration

email_utils.py
from django.core.mail import send_mail
from django.conf import settings
import requests


def send_checked_email(to_email, subject, message, from_email=None):
    """Send email only if recipient is not suppressed."""
    # Check suppression list
    url = f"{settings.PARSEBOUNCE_URL}/projects/{settings.PARSEBOUNCE_PROJECT_ID}/suppressions/check"
    response = requests.get(
        url,
        params={"email": to_email},
        headers={"X-API-Key": settings.PARSEBOUNCE_API_KEY}
    )


    if response.ok and response.json().get("suppressed"):
        # Log and skip
        import logging
        logging.info(f"Skipping suppressed email: {to_email}")
        return False


    # Send the email
    send_mail(
        subject,
        message,
        from_email or settings.DEFAULT_FROM_EMAIL,
        [to_email],
    )
    return True

PHP

ParseBounce.php
<?php


class ParseBounce
{
    private string $apiKey;
    private string $projectId;
    private string $baseUrl = 'https://api.parsebounce.com';


    public function __construct(string $apiKey, string $projectId)
    {
        $this->apiKey = $apiKey;
        $this->projectId = $projectId;
    }


    public function isSuppressed(string $email): bool
    {
        $url = sprintf(
            '%s/projects/%s/suppressions/check?%s',
            $this->baseUrl,
            $this->projectId,
            http_build_query(['email' => $email])
        );


        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-API-Key: ' . $this->apiKey
        ]);


        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);


        if ($httpCode !== 200) {
            return false; // Fail-open on error
        }


        $data = json_decode($response, true);
        return $data['suppressed'] ?? false;
    }


    public function filterSuppressed(array $emails): array
    {
        $url = sprintf(
            '%s/projects/%s/suppressions/check',
            $this->baseUrl,
            $this->projectId
        );


        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['emails' => $emails]));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json'
        ]);


        $response = curl_exec($ch);
        curl_close($ch);


        $data = json_decode($response, true);
        $valid = [];


        foreach ($data['results'] ?? [] as $result) {
            if (!$result['suppressed']) {
                $valid[] = $result['email'];
            }
        }


        return $valid;
    }
}


// Usage
$pb = new ParseBounce($_ENV['PARSEBOUNCE_API_KEY'], $_ENV['PARSEBOUNCE_PROJECT_ID']);


if (!$pb->isSuppressed('user@example.com')) {
    // Safe to send
}


$validEmails = $pb->filterSuppressed(['a@test.com', 'b@test.com']);

cURL

Check single email

curl -H "X-API-Key: $PARSEBOUNCE_API_KEY" \
  "https://api.parsebounce.com/projects/$PROJECT_ID/suppressions/check?email=test@example.com"

Batch check

curl -X POST \
  -H "X-API-Key: $PARSEBOUNCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["a@test.com", "b@test.com"]}' \
  "https://api.parsebounce.com/projects/$PROJECT_ID/suppressions/check"

Add to suppression list

curl -X POST \
  -H "X-API-Key: $PARSEBOUNCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "unsubscribed@example.com"}' \
  "https://api.parsebounce.com/projects/$PROJECT_ID/suppressions"
← ErrorsBack to Overview