---
title: "Get best email addresses by GitHub node IDs"
method: POST
path: "/api/users/best-email"
---

# Get best email addresses by GitHub node IDs

`POST /api/users/best-email`

Fetch the best email address for GitHub users by their node IDs. Uses intelligent selection to prioritize personal emails over work emails and verifies domain validity. Returns the best email plus all other email candidates. Supports batch requests (1-100 IDs). Requires RAW service. Credits: 1 per result returned.

## Request body

- GetBestEmailByIdRequest
  - `githubIds` string[], required — Array of GitHub node IDs (1-100)
  - `signals` EmailSignals — Optional signal data for tracking email context (body, subject, sender)
    - `emailBody` string — Email body content for tracking
    - `emailSubject` string — Email subject for tracking
    - `sender` string — Sender identifier for tracking
    - `repoReasonForEmail` string — Provide the repo ID for why you are emailing the user
    - `reasonForEmailNaturalLanguage` string — Provide the reason for emailing the user in natural language

## Response `200`

Best emails retrieved successfully

- BestEmailResponse
  - `results` BestEmailResult[], required — Array of best email results
    - `githubId` string, required — GitHub node ID
    - `login` string, required — GitHub username
    - `bestEmail` string, nullable, required — Best email address, or null if none available
    - `otherCandidates` string[], required — Other email addresses that were not selected as the best email
  - `count` number, required — Number of results returned

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - API key missing
- `403` — Forbidden - Invalid API key or RAW service access denied
- `429` — Too Many Requests - Hourly credit limit exceeded

## Changes

- **2025-11-17** `9a516df60a50` — 2 info
  - added the new optional request property `signals/reasonForEmailNaturalLanguage`
  - added the new optional request property `signals/repoReasonForEmail`
- **2025-11-17** `cd9fe36cf492` — 1 breaking
  - the response property `results/items/bestEmail` became nullable for the status `200`
- **2025-11-13** `7fbb203471f4` — 1 info
  - added the new optional request property `signals`
- **2025-11-13** `b2705a930628` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/bountylaboratories/apis/bounty-lab-public-api/changes/api/users/best-email/post.md)

---

[API](https://skmtc.dev/bountylaboratories/apis/bounty-lab-public-api.md) · [All operations](https://skmtc.dev/bountylaboratories/apis/bounty-lab-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bountylaboratories/apis/bounty-lab-public-api/revisions/4664c27f7e3a?raw)