# Check before sending

Ask before every email (or LinkedIn step) whether this person, company or address may be contacted now. One question instead of four sources: the answer is `allowed: true`, or `false` with the reasons. Read-only: nothing is created. Send one check, or `{ "checks": [...] }` with up to 100.

Reasons that block: `excluded`, `unsubscribed` or `bounced` (on the exclusions; `bounced` only for email), `archived`, `needs_decision` or `snoozed` (the person or their company), `not_interested`, `out_of_office`, `step_already_sent` (that email step went to this company already: to any address at its domain, by anyone; an email that bounced does not count), `replied` (they replied after your last email, by email as you logged it, with a referral, or on LinkedIn: answer them first), `meeting_booked` (a meeting is booked: no next step).

Pass `step` for a step of your sequence. Leave it out for an answer to someone who replied: then a reply or a meeting is a warning, not a reason. Someone a colleague referred you to (`referral` on POST /outreach/activity) is not blocked by what already went to that company: the warning `referred` says who referred them.

Warnings that do not block: `catch_all`, `unverifiable` or `not_found` (the address), `email_status_unknown`, `generic_address` (jobs@, info@ …), `no_email`, `referred`, `company_not_found` (nothing is known about the `company` you passed: no saved row, no domain, nobody in Leads works there; only the exclusions were checked on it).

The company does not have to be saved: a company in Companies through its leads, or only its domain, counts what went to its people and to any address at its domain (`company.id` is then null).

A domain on the exclusions also catches a company known only by its name (`cloudnest.io` and a lead at "Cloudnest"), and a company name on the exclusions catches an address on a domain with that name. When the company has a domain of its own, that domain decides: pass `company` as a domain when you know it.

## Authentication

Send `Authorization: Bearer gtk_…`. Create the key under **Connect assistant → API keys**. Every `gtk_` key can call these routes, also while the Signals API is closed. A missing, invalid or revoked key is **401**.

### Body parameters

- **`lead`** `string` — The person: a row id, a LinkedIn URL or their address.
- **`company`** `string` — The company: a row id, its domain, page or name.
- **`email`** `string` — The address you want to mail: a bare address (`anna@acme.com`), not `Anna <anna@acme.com>` or `mailto:`.
- **`step`** `integer` — Which step of your sequence (1 = the first email). Leave it out for an answer to someone who replied.
- **`channel`** `string` — Default `email`. For `linkedin`, a bounced address and your email steps do not block. One of: `email`, `linkedin`.
- **`checks`** `object[]` — Instead of the fields above: up to 100 checks, each with these fields.

## Response

- **`allowed`** `boolean` · **required** — May go out now. With `checks`: true only when every check may.
- **`reasons`** `object[]` · **required** — What blocks it: `code` and `message`.
- **`warnings`** `object[]` · **required** — What does not block it: `code` and `message`.
- **`person`** `object | null` · **required** — The person it found: `id` (null for someone who is only in a LinkedIn conversation, not in the Leads table: `save_leads` adds them), `name`.
- **`company`** `object | null` · **required** — The company it checked: `id` (null when it is not saved), `name`, `domain`.
- **`email`** `string | null` · **required** — The address it checked.
- **`email_status`** `string | null` · **required** — What mySDR knows about that address.
- **`history`** `object` · **required** — `emails_sent` (that arrived), `emails_bounced`, `steps_sent`, `last_sent_at`, `last_reply_at`, `last_meeting_at`: to this person, their company and its people, from every address.
- **`allowed_count / blocked_count / results`** `integer / integer / object[]` — With `checks`: how many may go out and how many are blocked, and each answer above in order.

## Credits

Free. This call never uses credits.

## Errors

- **400** `invalid_request` — An unknown field, a check without `lead`, `company` or `email`, an `email` that is not a bare address, or more than 100 checks.
- **401** `authentication_error` — The Authorization header is missing, or the key is unknown or revoked.
- **403** `permission_error` — API access is not part of your plan, or your account is suspended.
- **429** `rate_limit_error` — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header.
- **503** `service_unavailable` — The API is temporarily unavailable. Retry later.
- **500** `internal_error` — Something went wrong on our side.

## Example

### cURL

```bash
curl -X POST "https://mysdr.app/api/v1/outreach/check" \
  -H "Authorization: Bearer $MYSDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "acme-logistics.example",
    "email": "info@acme-logistics.example",
    "step": 1
  }'
```

### JavaScript

```javascript
const response = await fetch('https://mysdr.app/api/v1/outreach/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MYSDR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "company": "acme-logistics.example",
    "email": "info@acme-logistics.example",
    "step": 1
  })
});
const body = await response.json();
```

### Python

```python
import json
import os
import urllib.request

payload = {
  "company": "acme-logistics.example",
  "email": "info@acme-logistics.example",
  "step": 1
}

request = urllib.request.Request(
    "https://mysdr.app/api/v1/outreach/check",
    headers={
    "Authorization": f"Bearer {os.environ['MYSDR_API_KEY']}",
    "Content-Type": "application/json"
    },
    data=json.dumps(payload).encode(),
    method="POST",
)
with urllib.request.urlopen(request) as response:
    body = json.load(response)
```

### Example response

```json
{
  "allowed": false,
  "reasons": [
    {
      "code": "step_already_sent",
      "message": "Step 1 already went to Acme Logistics (jobs@acme-logistics.example, 22 Oct 2026)."
    }
  ],
  "warnings": [
    {
      "code": "email_status_unknown",
      "message": "mySDR has no verification status for info@acme-logistics.example."
    },
    {
      "code": "generic_address",
      "message": "info@acme-logistics.example is a general address, not a person."
    }
  ],
  "person": null,
  "company": {
    "id": "sav_2b9e8d10-7f4a-4a51-8c2e-5d1f0a3b6c77",
    "name": "Acme Logistics",
    "domain": "acme-logistics.example"
  },
  "email": "info@acme-logistics.example",
  "email_status": null,
  "history": {
    "emails_sent": 1,
    "emails_bounced": 0,
    "steps_sent": [
      1
    ],
    "last_sent_at": "2026-10-22T08:31:00.000Z",
    "last_reply_at": null,
    "last_meeting_at": null
  }
}
```