Code examples

Every example calls POST /v1/check with a secret key from the IBE_API_KEY environment variable, sets a timeout, and reads recommendation. To try them without a key, use a test address such as workspace@test.isbusinessemail.com and drop the auth header.

curl

curl -s https://api.isbusinessemail.com/v1/check \
  --max-time 3 \
  -H "Authorization: Bearer $IBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.io"}' | jq '{category, recommendation, reasons}'

JavaScript (browser, publishable key)

In the browser, only ever use a publishable key restricted to your origin.

async function hintForEmail(email) {
  try {
    const res = await fetch('https://api.isbusinessemail.com/v1/check', {
      method: 'POST',
      headers: { Authorization: 'Bearer ibe_pub_…', 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(1500),
    });
    return res.ok ? await res.json() : null;
  } catch {
    return null; // stay quiet; the server decides on submit
  }
}

Node.js

Node 18+ has fetch built in. This helper fails open and is safe to drop into any signup route.

// isbusinessemail.js
const API = 'https://api.isbusinessemail.com/v1/check';

export async function checkEmail(email, { policy = 'b2b', timeoutMs = 2500 } = {}) {
  try {
    const res = await fetch(API, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.IBE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, policy }),
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (!res.ok) {
      const problem = await res.json().catch(() => ({}));
      console.warn('isBusinessEmail error', res.status, problem.code);
      return { recommendation: 'allow', failOpen: true };
    }
    return await res.json();
  } catch (err) {
    console.warn('isBusinessEmail unreachable', err.name);
    return { recommendation: 'allow', failOpen: true };
  }
}

Python (requests)

import os
import requests

API = "https://api.isbusinessemail.com/v1/check"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['IBE_API_KEY']}"


def check_email(email: str, policy: str = "b2b") -> dict:
    try:
        r = session.post(API, json={"email": email, "policy": policy}, timeout=(2, 3))
        if r.ok:
            return r.json()
        print("isBusinessEmail error", r.status_code)
    except requests.RequestException as exc:
        print("isBusinessEmail unreachable", exc)
    return {"recommendation": "allow", "fail_open": True}


result = check_email("jane@acme.io")
print(result["recommendation"], result.get("reasons"))

PHP

Uses the bundled cURL extension; no Composer packages needed.

<?php
function check_email(string $email, string $policy = 'b2b'): array
{
    $ch = curl_init('https://api.isbusinessemail.com/v1/check');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 2,
        CURLOPT_TIMEOUT        => 3,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('IBE_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode(['email' => $email, 'policy' => $policy]),
    ]);
    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

    if ($body === false || $status !== 200) {
        error_log("isBusinessEmail failed: HTTP $status " . curl_error($ch));
        return ['recommendation' => 'allow', 'fail_open' => true];
    }
    return json_decode($body, true);
}

$result = check_email('jane@acme.io');
echo $result['recommendation'], PHP_EOL;

Go

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type CheckResult struct {
	Category       string   `json:"category"`
	IsBusiness     bool     `json:"is_business"`
	Recommendation string   `json:"recommendation"`
	DidYouMean     *string  `json:"did_you_mean"`
	Reasons        []string `json:"reasons"`
	Workspace      struct {
		GoogleWorkspace struct {
			Detected bool `json:"detected"`
		} `json:"google_workspace"`
		Microsoft365 struct {
			Detected bool    `json:"detected"`
			TenantID *string `json:"tenant_id"`
		} `json:"microsoft_365"`
	} `json:"workspace"`
}

var client = &http.Client{Timeout: 3 * time.Second}

func CheckEmail(ctx context.Context, email string) (*CheckResult, error) {
	body, err := json.Marshal(map[string]string{"email": email})
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
		"https://api.isbusinessemail.com/v1/check", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("IBE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("isbusinessemail: HTTP %d", resp.StatusCode)
	}
	var out CheckResult
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		return nil, err
	}
	return &out, nil
}

func main() {
	res, err := CheckEmail(context.Background(), "jane@acme.io")
	if err != nil {
		fmt.Println("fail open:", err) // let the signup through, re-check later
		return
	}
	fmt.Println(res.Category, res.Recommendation, res.Reasons)
}

Ruby

Standard library only.

require "net/http"
require "json"

def check_email(email, policy: "b2b")
  uri = URI("https://api.isbusinessemail.com/v1/check")
  req = Net::HTTP::Post.new(uri)
  req["Authorization"] = "Bearer #{ENV.fetch('IBE_API_KEY')}"
  req["Content-Type"] = "application/json"
  req.body = { email: email, policy: policy }.to_json

  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 2, read_timeout: 3) do |http|
    http.request(req)
  end
  return JSON.parse(res.body) if res.is_a?(Net::HTTPSuccess)

  warn "isBusinessEmail error: #{res.code}"
  { "recommendation" => "allow", "fail_open" => true }
rescue StandardError => e
  warn "isBusinessEmail unreachable: #{e.class}"
  { "recommendation" => "allow", "fail_open" => true }
end

puts check_email("jane@acme.io")["recommendation"]

Java

Java 11+ HttpClient with Jackson for JSON (build JSON with a library, never by string concatenation of user input).

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;

public class IsBusinessEmail {
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(2))
            .build();
    private static final ObjectMapper JSON = new ObjectMapper();

    public static JsonNode check(String email) throws Exception {
        String body = JSON.writeValueAsString(Map.of("email", email));
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.isbusinessemail.com/v1/check"))
                .timeout(Duration.ofSeconds(3))
                .header("Authorization", "Bearer " + System.getenv("IBE_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
        HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 200) {
            throw new IllegalStateException("isBusinessEmail HTTP " + response.statusCode());
        }
        return JSON.readTree(response.body());
    }

    public static void main(String[] args) {
        try {
            JsonNode result = check("jane@acme.io");
            System.out.println(result.get("category").asText() + " " + result.get("recommendation").asText());
        } catch (Exception e) {
            System.out.println("fail open: " + e.getMessage()); // allow the signup, re-check later
        }
    }
}

C# (.NET 6+)

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Serialization;

// Reuse one HttpClient (or IHttpClientFactory) for the lifetime of your app.
var http = new HttpClient { Timeout = TimeSpan.FromSeconds(3) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("IBE_API_KEY"));

try
{
    var response = await http.PostAsJsonAsync(
        "https://api.isbusinessemail.com/v1/check",
        new { email = "jane@acme.io", policy = "b2b" });
    response.EnsureSuccessStatusCode();
    var result = await response.Content.ReadFromJsonAsync<CheckResult>();
    Console.WriteLine($"{result!.Category} {result.Recommendation}");
}
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
{
    Console.WriteLine($"fail open: {ex.Message}"); // allow the signup, re-check later
}

public record CheckResult(
    [property: JsonPropertyName("category")] string Category,
    [property: JsonPropertyName("is_business")] bool IsBusiness,
    [property: JsonPropertyName("recommendation")] string Recommendation,
    [property: JsonPropertyName("did_you_mean")] string? DidYouMean,
    [property: JsonPropertyName("reasons")] string[] Reasons);

Batch (Python)

import os
import requests

emails = ["jane@acme.io", "bob@gmail.com", "info@contoso.com"]
r = requests.post(
    "https://api.isbusinessemail.com/v1/check/batch",
    json={"items": emails},
    headers={"Authorization": f"Bearer {os.environ['IBE_API_KEY']}"},
    timeout=10,
)
r.raise_for_status()
for item in r.json()["results"]:
    print(item["email"], item["category"], item["recommendation"])

More on batching: Batch checks. Framework-specific guides: Express, Laravel, Django, Rails.