---
title: "Senders"
description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with."
url: "https://nextmail.sh/docs/api/reference/senders"
area: "API"
category: "Reference"
---

# Senders

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

## Operations

What is known about the organisation behind a sender: the line the reading pane shows under an unfamiliar sender, kept per domain and shared by every workspace.

### `GET /senders/{email}`

Read what is known about a sender

A sentence or two about the organisation behind the domain of the address, once it has been looked up. Every address under a domain shares its answer, a subdomain such as `mail.stripe.com` included, and an answer older than 30 days is looked up again by itself. A domain nobody has looked up yet is a 404, and so are personal mailbox providers such as Gmail and the domains of this workspace: `POST /senders/{email}/research` looks a domain up.

Requires the `threads:read` scope.

- Scopes: `threads:read`.

**Path parameters**

- `email` (`string`, required): An address of the sender, such as `billing@stripe.com`. Only its domain is read.

**Returns**

- `200` `SenderProfile`: What is known about the sender.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.senders.get()`](https://nextmail.sh/docs/sdk/reference/senders#get); Python [`senders.get()`](https://nextmail.sh/docs/python/reference/senders#get); Ruby [`senders.get`](https://nextmail.sh/docs/ruby/reference/senders#get); PHP [`senders->get`](https://nextmail.sh/docs/php/reference/senders#get); Go [`Senders.Get`](https://nextmail.sh/docs/go/reference/senders#get); Java [`senders().get`](https://nextmail.sh/docs/java/reference/senders#get); C# [`Senders.GetAsync`](https://nextmail.sh/docs/csharp/reference/senders#get); CLI [`nextmail senders get`](https://nextmail.sh/docs/cli/reference/senders#senders-get); MCP [`getSenderProfile`](https://nextmail.sh/docs/mcp/tools/reading#getSenderProfile).

### `POST /senders/{email}/research`

Look a sender up

Searches the web for the organisation behind the domain of the address and keeps what it found, as the reading pane does the first time it shows a sender. Every address under the domain shares the answer, a subdomain included, and it is kept for 30 days before it is looked up again, so a domain that was looked up before is answered from what was kept and nothing is searched. Personal mailbox providers such as Gmail and the domains of this workspace are never looked up. Only the owner of the workspace may look senders up, with a key or an app that is not limited to particular addresses or domains, and a workspace looks up at most 200 new domains a day.

Requires the `threads:read` scope.

- Scopes: `threads:read`.

**Path parameters**

- `email` (`string`, required): An address of the sender, such as `billing@stripe.com`. Only its domain is read.

**Returns**

- `200` `SenderProfile`: What was found.

**Errors**

- `404`: Nothing could be found about the domain, or it is a personal mailbox provider or a domain of this workspace.
- `409`: `ai_not_configured`: looking senders up is not available on this server.
- `429`: `research_limit_reached`: the workspace has looked up 200 new domains today. `rate_limited`: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in `Retry-After`.
- The errors every operation can return: `400`, `401`, `403`, `422`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`nextmail.senders.research()`](https://nextmail.sh/docs/sdk/reference/senders#research); Python [`senders.research()`](https://nextmail.sh/docs/python/reference/senders#research); Ruby [`senders.research`](https://nextmail.sh/docs/ruby/reference/senders#research); PHP [`senders->research`](https://nextmail.sh/docs/php/reference/senders#research); Go [`Senders.Research`](https://nextmail.sh/docs/go/reference/senders#research); Java [`senders().research`](https://nextmail.sh/docs/java/reference/senders#research); C# [`Senders.ResearchAsync`](https://nextmail.sh/docs/csharp/reference/senders#research); CLI [`nextmail senders research`](https://nextmail.sh/docs/cli/reference/senders#senders-research); MCP [`getSenderProfile`](https://nextmail.sh/docs/mcp/tools/reading#getSenderProfile).

### Objects

#### `SenderProfile`

`object`

- `object` (`string`, required, one of `"sender_profile"`)
- `domain` (`string`, required): The domain that was looked up: the organisation's own domain, which its subdomains share.
- `about` (`string`, required, up to 400 characters): A sentence or two in plain prose about the organisation behind it.
- `updatedAt` (`string`, required, format `date-time`): When it was last looked up.