How to Clean an Email List and Cut Your Bounce Rate (With the LeadOcean API)

Clean a list in four passes: dedupe, drop addresses that should never get a send, check the rest against a stored status, and replace stale work emails. The first two passes are free and local. The third spends records.

TL;DR

• Four passes take about 30 minutes for a few thousand addresses. Most of that is the status check running at your plan's rate limit.
• Cost: one LeadOcean record per address we hold. An address we hold nothing for is a 404 and costs nothing.
• The Free plan (1,000 records for life, no card) cleans up to 1,000 addresses. Paid plans have a fair-use pace, not credits.

Prerequisites

• A LeadOcean API key in $LEADOCEAN_API_KEY. Start free, no card.
• Your list as list.csv with an email column.
• Python 3 with requests, and curl.
• Know your rate limit: 5 requests a second on Free, 50 on Solo, 200 on Agency (see pricing).

Step 1: Dedupe and normalize

Verification spends a record per hit, so remove repeats first. Lowercase, trim, and collapse the same address written twice.

import csv

seen, rows = set(), []
for r in csv.DictReader(open("list.csv")):
    e = r["email"].strip().lower()
    if e and "@" in e and e not in seen:
        seen.add(e)
        rows.append(e)

print(len(rows), "unique addresses")
open("step1.txt", "w").write("\n".join(rows))

Do not collapse j.doe@acme.com and jane.doe@acme.com yet. They may be two real mailboxes. The status check in Step 3 settles it.

Step 2: Drop what should never get a send

Role addresses (info@, sales@) go to shared inboxes and draw complaints. Throwaway domains are never worth mailing. Drop both before you spend anything.

ROLE = {"info", "sales", "support", "admin", "contact", "hello", "office", "billing", "noreply"}
DISPOSABLE = {"mailinator.com", "guerrillamail.com", "10minutemail.com"}  # extend with your own list

keep = []
for e in open("step1.txt").read().split():
    local, domain = e.split("@", 1)
    if local in ROLE or domain in DISPOSABLE:
        continue
    keep.append(e)

print(len(keep), "left")
open("step2.txt", "w").write("\n".join(keep))

This catches obvious cases only. LeadOcean also labels role, disposable, spam_trap and abuse as statuses, so the next step catches the rest for addresses we hold.

Step 3: Check each address against its stored status

Enrich by email. The response carries email_status and email_type for that person. Send reveal_email true to also get the address list with a status per address.

curl -s -X POST https://api.leadocean.io/v1/people/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@acme.com", "reveal_email": true}'

Run it over the list, paced to your plan:

import os, time, json, requests

H = {"x-api-key": os.environ["LEADOCEAN_API_KEY"], "Content-Type": "application/json"}
PER_SEC = 5  # Free. Use 50 on Solo, 200 on Agency.
out = []

for e in open("step2.txt").read().split():
    r = requests.post("https://api.leadocean.io/v1/people/enrich",
                      headers=H, json={"email": e, "reveal_email": True})
    if r.status_code == 404:
        out.append({"email": e, "status": "not_held"})   # free, and not a verdict
    elif r.status_code == 200:
        d = r.json()["data"]["contact_data"]
        pid = r.json()["data"].get("meta", {}).get("source_ids", {}).get("person_id")
        out.append({"email": e, "status": d.get("email_status"), "type": d.get("email_type"), "person_id": pid})
    elif r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", 1)))
    else:
        r.raise_for_status()
    time.sleep(1 / PER_SEC)

json.dump(out, open("checked.json", "w"), indent=1)

A 404 means we hold nothing for that person. It does not mean the address is bad. Put those on a hold list and test them with your own verifier. If you need to retry after a 429, requeue the address; the loop above skips it.

Step 4: Sort by status

Act on the status, not on a feeling. The status values come from GET /v1/enums/email_status.

Also read email_type. A work_other address belongs to a former employer. It is the most likely to bounce or reach whoever inherited the mailbox.

send = [x for x in out if x["status"] in ("verified", "catch_all_valid")]
careful = [x for x in out if x["status"] == "catch_all"]
stale = [x for x in out if x.get("type") == "work_other"]
drop = [x for x in out if x["status"] in ("invalid", "disposable", "spam_trap", "abuse")]

LeadOcean does not refund bounces. Read email_status before you send, not after.

Step 5: Re-find stale addresses instead of deleting them

A work_other address means the person moved. The contact is still worth keeping. The Step 3 loop saved each person's id from data.meta.source_ids.person_id. Pass it to the work-email endpoint.

curl -s "https://api.leadocean.io/v2/people/email/work?person_id=PERSON_ID" \
  -H "x-api-key: $LEADOCEAN_API_KEY"

This returns one address at the current employer's domain, or data: null. It only returns addresses that are verified, catch_all_valid or catch_all. The call costs one record, including when it finds nothing. A null means none that qualify, not that the person has no email.

What you get

This is the response shape from the API reference at api.leadocean.io/openapi.json, with placeholder values. It is not a real person.

{
  "success": true,
  "data": {
    "contact_data": {
      "has_email": true,
      "email_status": "verified",
      "email_type": "work",
      "contact_emails": [
        {
          "email": "jane.doe@acme.com",
          "type": "work",
          "status": "verified",
          "verified_batch_date": "2026-09-20"
        }
      ]
    }
  },
  "meta": {}
}

verified_batch_date is the date of the verification run, not a timestamp for the address. Null there means the check was not ours.

You can size the mailable share of an audience for free before you buy a list to replace the dropped rows. Counts from leadocean_count_leads on 2026-10-21, for VPs in Sales & Business Development located in Canada:

Read the table as a filter, not a mailable count. Only about three in ten people in this audience carry an address in the default sendable set. The count call spends no records.

A search count of verified is an upper bound. The API reference says a person can read verified in a search row and untested when enriched, and the enriched answer is the correct one. Confirm on enrichment, as in Step 3.

Troubleshooting

FAQ