Leads

Get a lead's email status

GEThttps://api.ruuster.com/v1/leads/email-status

Ruuster's verdict on a lead's email address, by email, CRM id or lead id: valid, invalid, blocked, soft bounce, complaint, unsubscribed or unknown, with the code and reason behind it and since when.

Authentication: x-api-key and x-email headers of an owner or admin
Rate limit: lookup call, 20 per minute per key, within the 120 per minute
Rows count against the daily lead-row quota (50,000 by default)

View as Markdown

Ruuster checks every lead's address before it sends (a pre-send verification) and records what happens when it does send (bounces, blocks and drops from the mail provider, unsubscribes and spam reports). This endpoint turns that history into one verdict per lead. It is the same verdict the lead.email_status_changed webhook event carries. The Email status guide explains the statuses, the webhook, and how to keep the verdict in your CRM as custom fields.

Query parameters

Name	Type	Description
`email`	string	Case-insensitive. Returns every lead with that address, as Find a lead does
`crmExternalId`	string	Exact match on the lead's id in your CRM
`leadId`	string	A `leadId` from any other endpoint or event (`user:…` or `unregistered:…`)

Send exactly one of the three, otherwise 400 invalid_parameter. The lookup works even when lead contact details are off; the response then leaves out email, phone and checkedEmail.

Statuses

`status`	Means	Typical `code`
`valid`	Ruuster is delivering to the address
`invalid`	The mailbox does not exist, is disabled or closed, is disposable or a spam trap, or the address is on the bounce list. Call instead	`5.1.1 bounce`, `554 bounce`, `invalid`, `disposable`, `bounced address`
`blocked`	The recipient's mail provider refused the message for policy, reputation or content reasons; the mailbox itself may be fine	`5.7.1 block`, `5.7.515 block`
`soft_bounce`	A temporary problem: the mailbox is full, or their server did not answer. The address may still be good	`4.2.2 block`, `inbox_full`, `5.2.2 bounce`
`complaint`	The lead reported a Ruuster email as spam, so sends to them are dropped	`spam reporting address`
`unsubscribed`	The lead unsubscribed from Ruuster emails, or the CRM record carries an opt-out tag	`unsubscribed by the lead`, `unsubscribed address`, `crm: Do Not Email`
`unknown`	Not verified yet, or the check could not decide	`never verified`, `unknown`, `auto-unsubscribed`

Precedence when several things are true: delivery on is always valid; the lead's own unsubscribe outranks a later bounce; a recorded failure outranks a CRM opt-out tag.

Response

data.leads lists every match. Each has the short lead form (leadId, names, contact details when on, crmExternalId, crmStatus, crmTags, agentId, createdAt, lastLoginAt), then emailStatus:

Field	Description
`status`	The verdict, one of the seven above
`code`	What is behind it: the SMTP code and whether it was a bounce or a block, the verification status, or the suppression reason. `null` when valid
`reason`	One sentence, in plain words
`source`	Where the verdict comes from: `platform` (the delivery flags), `verification` (the pre-send check), `delivery` (a send), `lead` (they unsubscribed), `crm` (an opt-out tag)
`checkedEmail`	The address the verdict is about (only when lead contact details are on)
`failedAt`	When the failure behind the verdict was recorded, if there is one
`since`	When the verdict last changed. `null` when it was classified on this call, for a lead the 15-minute scan hasn't stored yet or whose address changed since; then there is no history
`previousStatus`	The verdict before this one, when known

More than one lead is normal for an email: the same person can be a registered user and a CRM contact. No match returns an empty list with 200.

Request

curl -s "https://api.ruuster.com/v1/leads/email-status?email=sam.lee%40example.com" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"

const res = await fetch("https://api.ruuster.com/v1/leads/email-status?email=sam.lee%40example.com", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);

import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/leads/email-status?email=sam.lee%40example.com",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])

{ "ok": true, "data": { "leads": [ { "leadId": "user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04", "firstName": "Sam", "lastName": "Lee", "email": "sam.lee@example.com", "phone": "+15205550142", "crmExternalId": "48213", "crmStatus": "Showing Homes Nurture", "crmTags": ["buyer", "tucson"], "agentId": "7c1e9b42-3d85-4a6f-9e07-1b2c8d4f5a69", "createdAt": "2026-09-21T18:20:05Z", "lastLoginAt": "2026-09-30T02:11:40Z", "emailStatus": { "status": "invalid", "code": "5.1.1 bounce", "reason": "The mailbox does not exist or no longer accepts mail.", "source": "delivery", "checkedEmail": "sam.lee@example.com", "failedAt": "2026-10-29T14:02:11Z", "since": "2026-10-29T14:10:00Z", "previousStatus": "valid" }, "links": { "activity": "/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/activity", "emails": "/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/emails" } } ] }, "meta": { "brokerageId": "4f6c2a9e-8d31-4b57-9a0e-2c7d5e1b8f43" } }