# API: Deliverability

| Method | Path | What it does | Scope |
|---|---|---|---|
| GET | `/v1/deliverability/dns` | For a sending domain: SPF, DKIM and DMARC, the records to add, and what has to be done by hand | `sequences:read` |
| POST | `/v1/deliverability/dns/apply` | Add the planned records you approve through Cloudflare (owners, signed in; only records the current plan calls for) (web app only) | `settings:write` |
| GET | `/v1/deliverability/health` | Each sending mailbox's health (healthy, warning, cooldown, paused, disconnected) with reasons and its daily history (with the numbers to chart), each of a person's mailboxes, and each domain's own history; ?sequence_id= for a sequence's senders | `sequences:read` |
| DELETE | `/v1/deliverability/mailboxes/:user_id/cooldown` | End a cooldown early (an owner; or the person, for one they started) (web app only) | `sequences:write` |
| POST | `/v1/deliverability/mailboxes/:user_id/cooldown` | Cool a mailbox down: it sends a fraction of its daily limit (a quarter by default) for 1–14 days (your own, or any for an owner) (web app only) | `sequences:write` |
| POST | `/v1/deliverability/placement-tests` | Send a seed placement test from a mailbox (yours, or any for an owner): the vendor's seed addresses report inbox, spam or missing per provider (web app only) | `messages:send` |
| GET | `/v1/deliverability/utilization` | Per mailbox and for the organization: today's limit, sent, in flight, due, backlog by sequence, days to clear, and recommendations | `sequences:read` |
| POST | `/v1/me/mailbox-health/check` | Check your mailbox's health now (DNS, blocklists, Postmaster Tools when connected) and record it (web app only) | `sequences:read` |
| GET | `/v1/sender-invites` | Sender invitations (all for owners; yours otherwise), with whether each mailbox is connected | `sequences:read` |
| POST | `/v1/sender-invites` | Invite a teammate to connect their Gmail or Outlook as a sender (they get a link to Settings → Integrations) | `settings:write` |
| POST | `/v1/sender-invites/:id/cancel` | Cancel a pending sender invitation | `settings:write` |
| PUT | `/v1/settings/cloudflare` | Set (or remove) the organization's Cloudflare API token for adding SPF and DMARC records (owners, signed in; stored encrypted) (web app only) | `integrations:write` |
| GET | `/v1/settings/deliverability` | Health thresholds, the organization's daily limit, LinkedIn task limits and blocklist zones | `sequences:read` |
| PUT | `/v1/settings/deliverability` | Change deliverability settings (owners, signed in; raising a LinkedIn limit above its default needs a reason) (web app only) | `settings:write` |

## Examples

### GET /v1/deliverability/dns

For a sending domain: SPF, DKIM and DMARC, the records to add, and what has to be done by hand

```bash
curl -s "https://api.closefinch.com/v1/deliverability/dns" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/deliverability/dns`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/deliverability/health

Each sending mailbox's health (healthy, warning, cooldown, paused, disconnected) with reasons and its daily history (with the numbers to chart), each of a person's mailboxes, and each domain's own history; ?sequence_id= for a sequence's senders

```bash
curl -s "https://api.closefinch.com/v1/deliverability/health" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/deliverability/health`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/deliverability/utilization

Per mailbox and for the organization: today's limit, sent, in flight, due, backlog by sequence, days to clear, and recommendations

```bash
curl -s "https://api.closefinch.com/v1/deliverability/utilization" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/deliverability/utilization`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### GET /v1/sender-invites

Sender invitations (all for owners; yours otherwise), with whether each mailbox is connected

```bash
curl -s "https://api.closefinch.com/v1/sender-invites" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/sender-invites`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

### POST /v1/sender-invites

Invite a teammate to connect their Gmail or Outlook as a sender (they get a link to Settings → Integrations)

```bash
curl -s -X POST "https://api.closefinch.com/v1/sender-invites" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/sender-invites`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### POST /v1/sender-invites/$ID/cancel

Cancel a pending sender invitation

```bash
curl -s -X POST "https://api.closefinch.com/v1/sender-invites/$ID/cancel" \
  -H "Authorization: Bearer $RA_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```js
const res = await fetch(`https://api.closefinch.com/v1/sender-invites/${id}/cancel`, {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({}), // fields: see the OpenAPI schema
});
const data = await res.json();
```

### GET /v1/settings/deliverability

Health thresholds, the organization's daily limit, LinkedIn task limits and blocklist zones

```bash
curl -s "https://api.closefinch.com/v1/settings/deliverability" \
  -H "Authorization: Bearer $RA_API_KEY"
```

```js
const res = await fetch(`https://api.closefinch.com/v1/settings/deliverability`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.RA_API_KEY}` },
});
const data = await res.json();
```

Request and response schemas: [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json). All resources: [API reference](https://www.closefinch.com/docs/api).