Quickstart

export MOLEMAN_API_KEY="mm_test_..."

#!/usr/bin/env bash
# Moleman quickstart: your first working email in 3 calls.
# Needs: curl. Set MOLEMAN_API_KEY first (start with your mm_test_ key: free, made-up results).
set -euo pipefail
BASE="${MOLEMAN_BASE_URL:-https://moleman.io}"
AUTH="Authorization: Bearer ${MOLEMAN_API_KEY:?Set MOLEMAN_API_KEY to your API key}"

# 1. Check the key and your credits.
curl -sS "$BASE/api/v1/account" -H "$AUTH"
echo

# 2. Find Sarah Miller's email at brightsmiledental.com (waits up to 30 s for the answer).
ANSWER=$(curl -sS -X POST "$BASE/api/v1/find-contacts" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-$(date +%s)" \
  -d '{"rows":[{"firstName":"Sarah","lastName":"Miller","website":"brightsmiledental.com"}],"wait":30}')
echo "$ANSWER"
JOB_ID=$(echo "$ANSWER" | sed -n 's/.*"jobId":\([0-9]*\).*/\1/p')

# 3. Read the job until it is done (a big job takes longer than 30 s; this loop waits for it).
while true; do
  JOB=$(curl -sS "$BASE/api/v1/jobs/$JOB_ID" -H "$AUTH")
  case "$JOB" in
    *'"status":"done"'*|*'"status":"cancelled"'*|*'"status":"failed"'*) break ;;
  esac
  sleep 5
done
echo "$JOB" | sed -n 's/.*"email":"\([^"]*\)".*"result":"\([^"]*\)".*/Email: \1 (\2)/p'

// Moleman quickstart: your first working email in 3 calls. Node 18 or newer, no packages.
// Run: MOLEMAN_API_KEY=mm_test_... node quickstart.mjs   (start with your test key: free, made-up results)
import { randomUUID } from 'node:crypto';

const BASE = process.env.MOLEMAN_BASE_URL ?? 'https://moleman.io';
const KEY = process.env.MOLEMAN_API_KEY;
if (!KEY) throw new Error('Set MOLEMAN_API_KEY to your API key.');

async function call(method, path, body) {
  const response = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(body ? { 'Content-Type': 'application/json', 'Idempotency-Key': randomUUID() } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await response.json();
  if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message} (${data.error.docs_url})`);
  return data;
}

// 1. Check the key and your credits.
const account = await call('GET', '/api/v1/account');
console.log(`Key works (${account.key.mode}). Credits left: ${account.credits.balance}`);

// 2. Find Sarah Miller's email at brightsmiledental.com (waits up to 30 s for the answer).
let job = await call('POST', '/api/v1/find-contacts', {
  rows: [{ firstName: 'Sarah', lastName: 'Miller', website: 'brightsmiledental.com' }],
  wait: 30,
});

// 3. Read the job until it is done (a big job takes longer than 30 s; this loop waits for it).
while (!['done', 'cancelled', 'failed'].includes(job.status)) {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  job = await call('GET', `/api/v1/jobs/${job.jobId}`);
}
for (const row of job.results) console.log(`Email: ${row.email ?? 'none'} (${row.result ?? row.findStatusText})`);

# Moleman quickstart: your first working email in 3 calls. Python 3.8 or newer, no packages.
# Run: MOLEMAN_API_KEY=mm_test_... python quickstart.py   (start with your test key: free, made-up results)
import json
import os
import time
import urllib.error
import urllib.request
import uuid

BASE = os.environ.get("MOLEMAN_BASE_URL", "https://moleman.io")
KEY = os.environ["MOLEMAN_API_KEY"]


def call(method, path, body=None):
    headers = {"Authorization": f"Bearer {KEY}"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        headers["Idempotency-Key"] = str(uuid.uuid4())
        data = json.dumps(body).encode()
    request = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
    try:
        with urllib.request.urlopen(request, timeout=60) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        problem = json.load(error)["error"]
        raise SystemExit(f"{problem['code']}: {problem['message']} ({problem['docs_url']})")


# 1. Check the key and your credits.
account = call("GET", "/api/v1/account")
print(f"Key works ({account['key']['mode']}). Credits left: {account['credits']['balance']}")

# 2. Find Sarah Miller's email at brightsmiledental.com (waits up to 30 s for the answer).
job = call("POST", "/api/v1/find-contacts", {
    "rows": [{"firstName": "Sarah", "lastName": "Miller", "website": "brightsmiledental.com"}],
    "wait": 30,
})

# 3. Read the job until it is done (a big job takes longer than 30 s; this loop waits for it).
while job["status"] not in ("done", "cancelled", "failed"):
    time.sleep(5)
    job = call("GET", f"/api/v1/jobs/{job['jobId']}")
for row in job["results"]:
    print(f"Email: {row['email'] or 'none'} ({row['result'] or row['findStatusText']})")