Email search

Email search takes one email address and asks every source of the Email module what it publishes about it: public profiles, PGP key servers, developer forges and code-review sites, bug trackers and mailing-list archives. The answer lists only the sources that found something, such as a real name, a profile, a key or an account. Use it when you start from an address. Starting from a handle, use Username search. To check whether the address is in known data breaches, the breach search is free.

When to use it

You have an email address and want the person behind it: real name, profiles, linked accounts.
You are looking at a developer address: forges, code reviews, bug trackers and list archives often tie it to a real name.
You want public keys and the identities signed into them (extended sources).

Request

POST /v1/osint/email, with a JSON body.

Parameter	Type	Required	What it does
`email`	string	Yes	The email address, up to 254 characters, like `name@domain.com`. Surrounding spaces are dropped and case does not matter. It cannot start with `-`.
`extended`	boolean	No, default `false`	Also ask the extended sources: deeper data, 3 credits more.

Any other field is refused with 400 invalid_request, and nothing is charged.

curl https://api.orelys.io/v1/osint/email \
  -H "Authorization: Bearer $ORELYS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "extended": true }' \
  --max-time 160

const response = await fetch("https://api.orelys.io/v1/osint/email", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORELYS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane@example.com", extended: true }),
  signal: AbortSignal.timeout(100_000),
});

const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

for (const result of data.results) {
  console.log(result.label, result.extended ? "(extended)" : "");
  for (const row of result.data.rows) console.log(`  ${row.label}: ${row.value}`);
}
console.log(`Cost ${data.cost}, charged: ${data.charged}, credits left: ${data.credits.remaining}`);

import os
import requests

response = requests.post(
    "https://api.orelys.io/v1/osint/email",
    headers={"Authorization": f"Bearer {os.environ['ORELYS_API_KEY']}"},
    json={"email": "jane@example.com", "extended": True},
    timeout=100,
)
data = response.json()
if not response.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")

for result in data["results"]:
    print(result["label"], "(extended)" if result["extended"] else "")
    for item in result["data"]["lists"]:
        print(f"  {item['label']}: {', '.join(item['items'])}")
print("Charged:", data["charged"], "- credits left:", data["credits"]["remaining"])

A search asks its sources several at a time, and gives the ones that failed one more try. It answers once every source has answered, and after about 85 seconds at the latest: a source that has not answered by then counts as failed, and you get everything the others found. Set your HTTP client’s timeout to at least 100 seconds, as above. A client that hangs up early loses the answer and, past the daily allowance, the credits too.

What you get back

{
  "module": "email",
  "query": "jane@example.com",
  "extended": true,
  "count": 2,
  "results": [
    {
      "source": "gravatar",
      "label": "Gravatar",
      "extended": false,
      "data": {
        "found": true,
        "rows": [
          { "label": "Display name", "value": "Jane Example" },
          { "label": "Profile", "value": "https://gravatar.com/janeexample" }
        ],
        "lists": [{ "label": "Accounts", "items": ["github: janeexample", "mastodon: @jane@mastodon.social"] }]
      }
    },
    {
      "source": "github",
      "label": "GitHub",
      "extended": true,
      "data": {
        "found": true,
        "rows": [
          { "label": "Login", "value": "janeexample" },
          { "label": "Name", "value": "Jane Example" },
          { "label": "Profile", "value": "https://github.com/janeexample" }
        ],
        "lists": [{ "label": "Organizations", "items": ["example-org"] }]
      }
    }
  ],
  "sources": { "checked": 52, "found": 2, "not_found": 46, "failed": 4 },
  "cost": 4,
  "charged": true,
  "credits": { "remaining": 33 }
}

Field	What it is
`query`	The address searched, in lower case, without surrounding spaces.
`extended`	Whether the extended sources were asked.
`count`	Number of items in `results`.
`results`	Only the sources that found something. `[]` when none did.
`sources`	What happened across every source asked: `checked`, `found`, `not_found` (answered, nothing there) and `failed` (could not answer, or not in time).
`cost`	What the search costs: 1, or 4 with the extended sources.
`charged`	Whether the credits were taken. Also in the `X-Request-Charged` header.
`credits.remaining`	Your balance after this search. Also in the `X-Credits-Remaining` header.
`redacted`	Only there when results were left out because they mention a removed selector.

Each item of results has source (its id in the catalogue), label, extended, and data: rows (label and value pairs) and lists (a label and its items). Every source has its own labels, and any of them can be missing.

Results are untrusted text published by third parties. Show them as text, never as HTML, and do not follow their links automatically.

Cost and limits

Case	Credits
A search	1, or 4 with `"extended": true`. Never from your daily quota.
No source finds anything	0: `charged: false`, within a daily allowance (15 searches a day per account). Past it, charged like any search.
Not one source can be reached	0: `502 sources_unavailable`, credits always given back.
Connection closed during the search	0, within the same daily allowance: the search stops.
Invalid input, not enough credits, a limit reached	0: refused before anything runs.

Plans: Professional and Enterprise, the plans with API access. Both include the extended sources. Credits come in packs on the pricing page and never expire.
Per account: 60 searches a minute and 3 at the same time on Professional, 120 and 5 on Enterprise. They are shared with your other searches, through the API and on your dashboard.
Per address: 120 calls a minute, whatever the plan.

See Limits for the details.

Errors

Status	Code	When
`400`	`invalid_request`	A field is missing, unknown or invalid. `details` lists each problem. Nothing is charged.
`401`	`missing_api_key`, `invalid_api_key`	No key was sent, or it is not a valid one.
`402`	`insufficient_credits`	Your balance is below the cost of the search. The message gives both.
`403`	`plan_required`, `account_blocked`	The account is not on Professional or Enterprise, or it is blocked.
`429`	`rate_limited`, `concurrency_limited`, `ip_rate_limited`	A limit is reached. Wait `Retry-After` seconds.
`502`	`sources_unavailable`	Not one source could be reached. The credits are always given back.
`503`	`module_unavailable`	The module is down for a moment. Nothing is charged.
`503`	`module_maintenance`, `module_offline`	The Orelys team has paused this module, or all of Orelys OSINT. Nothing is charged. Under maintenance, wait `Retry-After` seconds.

Errors use the usual envelope: { "error": { "code": "…", "message": "…" } }.

Tips

Decide on extended per address. A standard search asks about 40 sources; the extended one adds about 10 more, such as GitHub, Google, Microsoft, the PGP key servers and ORCID. The catalogue lists them, with extended: true.
Start with the free breach search. POST /v1/breaches/check tells you, at no cost, which known breaches hold the address. Spend credits on Email search when you need the identity behind it.
Chain to Username search. A login or handle found here, such as janeexample above, goes straight to Username search.
Validate before you send. 400 invalid_request lists the problem in details, for example an address that does not look like name@domain.com. It costs nothing, but it still counts in your searches a minute.
Read failed apart from not_found. A failed source does not mean there is nothing there. When failed is high, try again later. A new search costs credits again, unless nothing is found.

Reference

Request and response schemas, every error, and a playground to try it.

Get started

Essentials

Intelligence X

OSINT

Data breaches

Privacy

Email search

When to use it

Request

What you get back

Cost and limits

Errors

Tips

Reference

Email search

​When to use it

​Request

​What you get back

​Cost and limits

​Errors

​Tips

​Reference

Email search

When to use it

Request

What you get back

Cost and limits

Errors

Tips

Reference