HeroBounce - Stop Email Bounces Before They Happen

Step-by-step guide to integrating email validation into your signup forms, CRM, and marketing automation workflows with best practices for performance and user experience.

Why Validate in Real-Time?

Real-time validation at the point of entry provides immediate benefits:

Instant feedback: Users can correct typos immediately
Cleaner data: Invalid addresses never enter your database
Better UX: Prevents failed signups due to typos
Cost savings: Don't pay to store and email invalid addresses

Basic API Integration

Single Email Validation

The most common use case: validate an email address when a user submits a form.

// Example API request
POST https://api.herobounce.com/v1/validate

{
  "email": "user@example.com"
}

// Response
{
  "email": "user@example.com",
  "valid": true,
  "status": "deliverable",
  "is_disposable": false,
  "is_role": false,
  "is_catch_all": false,
  "mx_records": true,
  "smtp_valid": true
}

Frontend Integration

For real-time validation on signup forms:

async function validateEmail(email) {
  const response = await fetch('https://api.herobounce.com/v1/validate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  const result = await response.json();

  if (!result.valid) {
    showError('Please enter a valid email address');
    return false;
  }

  if (result.is_disposable) {
    showError('Disposable email addresses are not allowed');
    return false;
  }

  return true;
}

Bulk Validation

For cleaning existing email lists:

POST https://api.herobounce.com/v1/validate/bulk

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ]
}

Best Practices

1. Implement Debouncing

Don't validate on every keystroke. Wait until the user stops typing:

let timeout;
emailInput.addEventListener('input', (e) => {
  clearTimeout(timeout);
  timeout = setTimeout(() => {
    validateEmail(e.target.value);
  }, 500); // Wait 500ms after user stops typing
});

2. Handle Errors Gracefully

API calls can fail. Don't block signups if validation is temporarily unavailable:

try {
  const result = await validateEmail(email);
  return result.valid;
} catch (error) {
  console.error('Validation API error:', error);
  // Allow signup to proceed but log for review
  return true;
}

3. Cache Results

If a user submits the same email multiple times, use cached results to reduce API calls:

const validationCache = new Map();

async function validateEmailWithCache(email) {
  if (validationCache.has(email)) {
    return validationCache.get(email);
  }

  const result = await validateEmail(email);
  validationCache.set(email, result);
  return result;
}

Rate Limiting

Most validation APIs have rate limits. Handle 429 responses with exponential backoff:

async function validateWithRetry(email, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(/* ... */);

      if (response.status === 429) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      return await response.json();
    } catch (error) {
      if (i === retries - 1) throw error;
    }
  }
}

Security Considerations

Never Expose API Keys in Frontend

Always call validation APIs from your backend. Exposing API keys in JavaScript allows anyone to use your quota. Use a backend proxy endpoint instead.

// Frontend: Call your backend
const result = await fetch('/api/validate-email', {
  method: 'POST',
  body: JSON.stringify({ email })
});

// Backend: Proxy to validation API
app.post('/api/validate-email', async (req, res) => {
  const { email } = req.body;

  const result = await fetch('https://api.herobounce.com/v1/validate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.HEROBOUNCE_API_KEY
    },
    body: JSON.stringify({ email })
  });

  res.json(await result.json());
});

Common Integration Patterns

Signup Forms

Validate on blur or with debounced input, show inline error messages

Import/CSV Upload

Use bulk validation endpoint, process in batches, show progress bar

CRM Integration

Validate on contact creation, add custom fields for validation results

Email Campaign Prep

Validate entire list before send, filter out invalid addresses automatically

Ready to Integrate?

Get your API key and start validating emails in minutes. Comprehensive documentation and code examples included.

Email Validation API: Integration Best Practices