Reference

Inboxes

Connected email accounts. Gmail and Outlook require the OAuth connect-link flow (a real browser session); SMTP/IMAP connects by credentials — no browser needed (POST /v1/inboxes/smtp).

List inboxes in the workspace

get /v1/inboxes 
curl -X GET "https://api.clement.so/v1/inboxes" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

Query parameters

  • limit integer
  • starting_after string
  • ending_before string
  • provider string
  • status string
  • tag string

Response200

OK

Property Type Description
object required enum (1)
"list"
data required array<Inbox>
has_more required boolean
next_cursor required string | null
prev_cursor required string | null
Example response 
{
  "object": "list",
  "data": [
    {
      "id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
      "object": "inbox",
      "mode": "live",
      "provider": "gmail",
      "email_address": "founder@acme.com",
      "display_name": "Alice from Acme",
      "status": "active",
      "status_reason": null,
      "daily_limit": 50,
      "effective_daily_limit": 26,
      "ramp": {
        "enabled": true,
        "start": 10,
        "end": 50,
        "days": 14,
        "started_at": "2026-04-22T09:00:00Z"
      },
      "signature_html": "<p>Alice<br>Acme</p>",
      "signature_text": "Alice\nAcme",
      "reply_to": null,
      "tags": [
        "outbound",
        "eu"
      ],
      "health_score": 92,
      "warmup_enabled": true,
      "timezone": "America/New_York",
      "last_send_at": "2026-04-29T14:32:11Z",
      "last_poll_at": "2026-04-29T15:00:04Z",
      "created_at": "2026-04-15T09:12:00Z",
      "revoked_at": null,
      "sandbox_config": null
    }
  ],
  "has_more": false,
  "next_cursor": "string",
  "prev_cursor": "string"
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.

Mint a one-time Gmail OAuth connect URL

post /v1/inboxes/google/connect_link

Returns a URL the customer/agent visits in a browser to OAuth-connect a Gmail inbox to this workspace. OAuth requires a browser session; the API layer cannot drive it directly. Agents typically DM the URL to a human, who clicks it and grants Google permissions. After consent, the inbox lands attached to the same workspace this key belongs to.

curl -X POST "https://api.clement.so/v1/inboxes/google/connect_link" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "redirect_url": "https://example.com"
    }'

Request body

Property Type Description
redirect_url string (uri) Where the dashboard sends the visitor after the OAuth callback completes. Must be `https://` and is only honored on the app's own origin (app.clement.so); any other origin falls back to the default, `/dashboard/inboxes`.

Response201

Connect URL minted

Property Type Description
url required string (uri) One-time URL the customer/agent visits in a browser to OAuth-connect a Gmail inbox. The token in the URL expires after 1 hour.
expires_at required string (date-time)
Example response 
{
  "url": "https://example.com/clement-webhook",
  "expires_at": "2026-04-29T10:00:00Z"
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.

Create a sandbox inbox (test mode only)

post /v1/inboxes/sandbox

Sandbox inboxes do not connect to a real provider. Sends targeting them transition straight to `sent` and the worker generates synthetic open / click / reply / bounce events on the configured schedule. Available only with a `cl_test_*` key — see API-PLAN §11.

curl -X POST "https://api.clement.so/v1/inboxes/sandbox" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "email_address": "alice@example.com",
      "display_name": "Alice's Inbox",
      "sandbox_config": {
        "open_probability": 0,
        "click_probability": 0,
        "reply_probability": 0,
        "bounce_probability": 0,
        "open_delay_seconds_min": 0,
        "open_delay_seconds_max": 0,
        "click_delay_seconds_min": 0,
        "click_delay_seconds_max": 0,
        "reply_delay_seconds_min": 0,
        "reply_delay_seconds_max": 0
      }
    }'

Request body

Property Type Description
email_address string (email) Optional. Synthetic email used to render the sandbox in lists and as the From address on synthetic outbound messages. Auto-generated as `sandbox-<short>@sandbox.clement.so` when omitted.
display_name string
sandbox_config object
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer

Response201

Created

Property Type Description
id required string
Example: "inb_AM788072KD0X99RP8HK5AH0000"
object required enum (1)
"inbox"
mode required enum (2) `live` for real-provider inboxes; `test` for sandbox inboxes.
"live""test"
provider required string
Example: "gmail"
email_address required string (email)
display_name required string | null
status required enum (8)
"connecting""active""token_expired""revoked""over_quota_today""unhealthy""paused""failed"
status_reason required string | null
daily_limit required integer Target maximum sends per day (inbox timezone). The ramp climbs toward it.
effective_daily_limit required integer Today's actual cap: `daily_limit`, or the ramp's value for today if lower.
ramp required InboxRamp
Show properties
Property Type Description
enabled required boolean
start required integer Cap on day 0 of the ramp.
end required integer Cap once the ramp completes (never above `daily_limit`).
days required integer Days to go from `start` to `end`.
started_at required string (date-time) Day 0 of the ramp (the connect time unless ramp-up was turned on later).
signature_html required string | null Appended to campaign sends, and to API sends / replies with `append_signature`.
signature_text required string | null Plain-text version of `signature_html`, derived on save.
reply_to required string | null Reply-To header on outgoing mail. null = replies go to `email_address`. Reply detection only sees inboxes connected to this workspace: a Reply-To outside them means replies aren't detected and sequences don't stop on reply.
tags required array<string> Workspace-scoped labels. Campaigns can pick senders by tag.
health_score required integer | null 0–100, null until first compute
warmup_enabled required boolean
timezone required string
Example: "Europe/Berlin"
last_send_at required string (date-time) | null
last_poll_at required string (date-time) | null
created_at required string (date-time)
revoked_at required string (date-time) | null
sandbox_config required SandboxConfig | null Populated only for `provider: 'sandbox'` inboxes; null otherwise.
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer
Example response 
{
  "id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "object": "inbox",
  "mode": "live",
  "provider": "gmail",
  "email_address": "founder@acme.com",
  "display_name": "Alice from Acme",
  "status": "active",
  "status_reason": null,
  "daily_limit": 50,
  "effective_daily_limit": 26,
  "ramp": {
    "enabled": true,
    "start": 10,
    "end": 50,
    "days": 14,
    "started_at": "2026-04-22T09:00:00Z"
  },
  "signature_html": "<p>Alice<br>Acme</p>",
  "signature_text": "Alice\nAcme",
  "reply_to": null,
  "tags": [
    "outbound",
    "eu"
  ],
  "health_score": 92,
  "warmup_enabled": true,
  "timezone": "America/New_York",
  "last_send_at": "2026-04-29T14:32:11Z",
  "last_poll_at": "2026-04-29T15:00:04Z",
  "created_at": "2026-04-15T09:12:00Z",
  "revoked_at": null,
  "sandbox_config": null
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.

Connect an SMTP/IMAP inbox

post /v1/inboxes/smtp

Connects a mailbox by credentials: SMTP for sending, IMAP for reply and bounce detection. Clement logs in to both servers before saving; if either login fails the call returns `422 inbox_connection_failed` and nothing is stored. Re-posting an already-connected SMTP address updates its credentials and reactivates it (200). Live mode only. Passwords are encrypted at rest and never returned. Port 25 is not supported.

curl -X POST "https://api.clement.so/v1/inboxes/smtp" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "email_address": "alex@acme.com",
      "display_name": "Alex from Acme",
      "smtp": {
        "host": "smtp.zoho.com",
        "port": 465,
        "security": "ssl",
        "username": "alex@acme.com",
        "password": "app-password"
      },
      "imap": {
        "host": "imap.zoho.com",
        "port": 993,
        "security": "ssl"
      }
    }'

Request body

Property Type Description
email_address required string (email)
Example: "alex@acme.com"
display_name string
smtp required InboxSmtpServer
Show properties
Property Type Description
host required string
Example: "smtp.example.com"
port required integer
Example: 465
security required enum (2) `ssl` = implicit TLS (465 / 993); `starttls` = upgrade on a plain port (587 / 143).
"ssl""starttls"
username string Login. Defaults to `email_address`.
password required string Password or app password. Stored encrypted; never returned.
imap required InboxImapServer
Show properties
Property Type Description
host required string
Example: "smtp.example.com"
port required integer
Example: 465
security required enum (2) `ssl` = implicit TLS (465 / 993); `starttls` = upgrade on a plain port (587 / 143).
"ssl""starttls"
username string Defaults to the SMTP username.
password string Defaults to the SMTP password.

Response200

Existing SMTP inbox reconnected with new credentials

Property Type Description
id required string
Example: "inb_AM788072KD0X99RP8HK5AH0000"
object required enum (1)
"inbox"
mode required enum (2) `live` for real-provider inboxes; `test` for sandbox inboxes.
"live""test"
provider required string
Example: "gmail"
email_address required string (email)
display_name required string | null
status required enum (8)
"connecting""active""token_expired""revoked""over_quota_today""unhealthy""paused""failed"
status_reason required string | null
daily_limit required integer Target maximum sends per day (inbox timezone). The ramp climbs toward it.
effective_daily_limit required integer Today's actual cap: `daily_limit`, or the ramp's value for today if lower.
ramp required InboxRamp
Show properties
Property Type Description
enabled required boolean
start required integer Cap on day 0 of the ramp.
end required integer Cap once the ramp completes (never above `daily_limit`).
days required integer Days to go from `start` to `end`.
started_at required string (date-time) Day 0 of the ramp (the connect time unless ramp-up was turned on later).
signature_html required string | null Appended to campaign sends, and to API sends / replies with `append_signature`.
signature_text required string | null Plain-text version of `signature_html`, derived on save.
reply_to required string | null Reply-To header on outgoing mail. null = replies go to `email_address`. Reply detection only sees inboxes connected to this workspace: a Reply-To outside them means replies aren't detected and sequences don't stop on reply.
tags required array<string> Workspace-scoped labels. Campaigns can pick senders by tag.
health_score required integer | null 0–100, null until first compute
warmup_enabled required boolean
timezone required string
Example: "Europe/Berlin"
last_send_at required string (date-time) | null
last_poll_at required string (date-time) | null
created_at required string (date-time)
revoked_at required string (date-time) | null
sandbox_config required SandboxConfig | null Populated only for `provider: 'sandbox'` inboxes; null otherwise.
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer
Example response 
{
  "id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "object": "inbox",
  "mode": "live",
  "provider": "gmail",
  "email_address": "founder@acme.com",
  "display_name": "Alice from Acme",
  "status": "active",
  "status_reason": null,
  "daily_limit": 50,
  "effective_daily_limit": 26,
  "ramp": {
    "enabled": true,
    "start": 10,
    "end": 50,
    "days": 14,
    "started_at": "2026-04-22T09:00:00Z"
  },
  "signature_html": "<p>Alice<br>Acme</p>",
  "signature_text": "Alice\nAcme",
  "reply_to": null,
  "tags": [
    "outbound",
    "eu"
  ],
  "health_score": 92,
  "warmup_enabled": true,
  "timezone": "America/New_York",
  "last_send_at": "2026-04-29T14:32:11Z",
  "last_poll_at": "2026-04-29T15:00:04Z",
  "created_at": "2026-04-15T09:12:00Z",
  "revoked_at": null,
  "sandbox_config": null
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.

Retrieve an inbox

get /v1/inboxes/{id} 
curl -X GET "https://api.clement.so/v1/inboxes/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

Path parameters

  • id string required

Response200

OK

Property Type Description
id required string
Example: "inb_AM788072KD0X99RP8HK5AH0000"
object required enum (1)
"inbox"
mode required enum (2) `live` for real-provider inboxes; `test` for sandbox inboxes.
"live""test"
provider required string
Example: "gmail"
email_address required string (email)
display_name required string | null
status required enum (8)
"connecting""active""token_expired""revoked""over_quota_today""unhealthy""paused""failed"
status_reason required string | null
daily_limit required integer Target maximum sends per day (inbox timezone). The ramp climbs toward it.
effective_daily_limit required integer Today's actual cap: `daily_limit`, or the ramp's value for today if lower.
ramp required InboxRamp
Show properties
Property Type Description
enabled required boolean
start required integer Cap on day 0 of the ramp.
end required integer Cap once the ramp completes (never above `daily_limit`).
days required integer Days to go from `start` to `end`.
started_at required string (date-time) Day 0 of the ramp (the connect time unless ramp-up was turned on later).
signature_html required string | null Appended to campaign sends, and to API sends / replies with `append_signature`.
signature_text required string | null Plain-text version of `signature_html`, derived on save.
reply_to required string | null Reply-To header on outgoing mail. null = replies go to `email_address`. Reply detection only sees inboxes connected to this workspace: a Reply-To outside them means replies aren't detected and sequences don't stop on reply.
tags required array<string> Workspace-scoped labels. Campaigns can pick senders by tag.
health_score required integer | null 0–100, null until first compute
warmup_enabled required boolean
timezone required string
Example: "Europe/Berlin"
last_send_at required string (date-time) | null
last_poll_at required string (date-time) | null
created_at required string (date-time)
revoked_at required string (date-time) | null
sandbox_config required SandboxConfig | null Populated only for `provider: 'sandbox'` inboxes; null otherwise.
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer
Example response 
{
  "id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "object": "inbox",
  "mode": "live",
  "provider": "gmail",
  "email_address": "founder@acme.com",
  "display_name": "Alice from Acme",
  "status": "active",
  "status_reason": null,
  "daily_limit": 50,
  "effective_daily_limit": 26,
  "ramp": {
    "enabled": true,
    "start": 10,
    "end": 50,
    "days": 14,
    "started_at": "2026-04-22T09:00:00Z"
  },
  "signature_html": "<p>Alice<br>Acme</p>",
  "signature_text": "Alice\nAcme",
  "reply_to": null,
  "tags": [
    "outbound",
    "eu"
  ],
  "health_score": 92,
  "warmup_enabled": true,
  "timezone": "America/New_York",
  "last_send_at": "2026-04-29T14:32:11Z",
  "last_poll_at": "2026-04-29T15:00:04Z",
  "created_at": "2026-04-15T09:12:00Z",
  "revoked_at": null,
  "sandbox_config": null
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.

Update an inbox's settings

patch /v1/inboxes/{id}

Sender name, daily limit and ramp-up, signature, reply-to, timezone and tags for any inbox; `warmup_enabled` for Gmail inboxes; `sandbox_config` for sandbox inboxes. Requires a write-scoped key.

curl -X PATCH "https://api.clement.so/v1/inboxes/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "display_name": "Alice's Inbox",
      "status": "active",
      "daily_limit": 0,
      "ramp": {
        "enabled": false,
        "start": 0,
        "end": 0,
        "days": 0
      },
      "signature_html": "string",
      "reply_to": "alice@example.com",
      "timezone": "Europe/Berlin",
      "tags": [
        "string"
      ],
      "warmup_enabled": false,
      "sandbox_config": {
        "open_probability": 0,
        "click_probability": 0,
        "reply_probability": 0,
        "bounce_probability": 0,
        "open_delay_seconds_min": 0,
        "open_delay_seconds_max": 0,
        "click_delay_seconds_min": 0,
        "click_delay_seconds_max": 0,
        "reply_delay_seconds_min": 0,
        "reply_delay_seconds_max": 0
      }
    }'

Path parameters

  • id string required

Request body

Property Type Description
display_name string | null Sender name shown in the From header. null clears it.
status enum (2) Only `active` ↔ `paused` transitions are allowed via PATCH, and only from `active` or `paused`.
"active""paused"
daily_limit integer Target maximum sends per inbox day (1–500).
ramp object Linear ramp from `start` to `end` over `days`, capped by `daily_limit`. Partial: unspecified fields keep their value.
Show properties
Property Type Description
enabled boolean Turning ramp-up on restarts it today.
start integer
end integer
days integer
signature_html string | null HTML signature. Scripts and event handlers are stripped; `signature_text` is derived. null or empty clears it.
reply_to string (email) | null Reply-To address for outgoing mail. null clears it. Use another inbox connected to this workspace: replies to an address Clement doesn't poll aren't detected, so sequences won't stop on reply.
timezone string IANA timezone (e.g. `Europe/Berlin`); defines the inbox's sending day.
Example: "Europe/Berlin"
tags array<string> Replaces the inbox's tags. Normalized to lowercase; letters, digits, spaces and - _ . / : only.
warmup_enabled boolean Gmail inboxes only. Joins or leaves the warmup pool; joining restarts the warmup ramp. Needs a paid plan (not during the trial).
sandbox_config object
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer

Response200

Updated

Property Type Description
id required string
Example: "inb_AM788072KD0X99RP8HK5AH0000"
object required enum (1)
"inbox"
mode required enum (2) `live` for real-provider inboxes; `test` for sandbox inboxes.
"live""test"
provider required string
Example: "gmail"
email_address required string (email)
display_name required string | null
status required enum (8)
"connecting""active""token_expired""revoked""over_quota_today""unhealthy""paused""failed"
status_reason required string | null
daily_limit required integer Target maximum sends per day (inbox timezone). The ramp climbs toward it.
effective_daily_limit required integer Today's actual cap: `daily_limit`, or the ramp's value for today if lower.
ramp required InboxRamp
Show properties
Property Type Description
enabled required boolean
start required integer Cap on day 0 of the ramp.
end required integer Cap once the ramp completes (never above `daily_limit`).
days required integer Days to go from `start` to `end`.
started_at required string (date-time) Day 0 of the ramp (the connect time unless ramp-up was turned on later).
signature_html required string | null Appended to campaign sends, and to API sends / replies with `append_signature`.
signature_text required string | null Plain-text version of `signature_html`, derived on save.
reply_to required string | null Reply-To header on outgoing mail. null = replies go to `email_address`. Reply detection only sees inboxes connected to this workspace: a Reply-To outside them means replies aren't detected and sequences don't stop on reply.
tags required array<string> Workspace-scoped labels. Campaigns can pick senders by tag.
health_score required integer | null 0–100, null until first compute
warmup_enabled required boolean
timezone required string
Example: "Europe/Berlin"
last_send_at required string (date-time) | null
last_poll_at required string (date-time) | null
created_at required string (date-time)
revoked_at required string (date-time) | null
sandbox_config required SandboxConfig | null Populated only for `provider: 'sandbox'` inboxes; null otherwise.
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer
Example response 
{
  "id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "object": "inbox",
  "mode": "live",
  "provider": "gmail",
  "email_address": "founder@acme.com",
  "display_name": "Alice from Acme",
  "status": "active",
  "status_reason": null,
  "daily_limit": 50,
  "effective_daily_limit": 26,
  "ramp": {
    "enabled": true,
    "start": 10,
    "end": 50,
    "days": 14,
    "started_at": "2026-04-22T09:00:00Z"
  },
  "signature_html": "<p>Alice<br>Acme</p>",
  "signature_text": "Alice\nAcme",
  "reply_to": null,
  "tags": [
    "outbound",
    "eu"
  ],
  "health_score": 92,
  "warmup_enabled": true,
  "timezone": "America/New_York",
  "last_send_at": "2026-04-29T14:32:11Z",
  "last_poll_at": "2026-04-29T15:00:04Z",
  "created_at": "2026-04-15T09:12:00Z",
  "revoked_at": null,
  "sandbox_config": null
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.

Delete an inbox (sandbox only via API)

delete /v1/inboxes/{id}

Hard-delete for sandbox inboxes. Real-provider (Gmail) disconnect still goes through the dashboard. `?confirm=true` required (high-blast-radius).

curl -X DELETE "https://api.clement.so/v1/inboxes/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

Path parameters

  • id string required

Query parameters

  • confirm string

Response200

Deleted

Property Type Description
id required string
Example: "inb_AM788072KD0X99RP8HK5AH0000"
object required enum (1)
"inbox"
mode required enum (2) `live` for real-provider inboxes; `test` for sandbox inboxes.
"live""test"
provider required string
Example: "gmail"
email_address required string (email)
display_name required string | null
status required enum (8)
"connecting""active""token_expired""revoked""over_quota_today""unhealthy""paused""failed"
status_reason required string | null
daily_limit required integer Target maximum sends per day (inbox timezone). The ramp climbs toward it.
effective_daily_limit required integer Today's actual cap: `daily_limit`, or the ramp's value for today if lower.
ramp required InboxRamp
Show properties
Property Type Description
enabled required boolean
start required integer Cap on day 0 of the ramp.
end required integer Cap once the ramp completes (never above `daily_limit`).
days required integer Days to go from `start` to `end`.
started_at required string (date-time) Day 0 of the ramp (the connect time unless ramp-up was turned on later).
signature_html required string | null Appended to campaign sends, and to API sends / replies with `append_signature`.
signature_text required string | null Plain-text version of `signature_html`, derived on save.
reply_to required string | null Reply-To header on outgoing mail. null = replies go to `email_address`. Reply detection only sees inboxes connected to this workspace: a Reply-To outside them means replies aren't detected and sequences don't stop on reply.
tags required array<string> Workspace-scoped labels. Campaigns can pick senders by tag.
health_score required integer | null 0–100, null until first compute
warmup_enabled required boolean
timezone required string
Example: "Europe/Berlin"
last_send_at required string (date-time) | null
last_poll_at required string (date-time) | null
created_at required string (date-time)
revoked_at required string (date-time) | null
sandbox_config required SandboxConfig | null Populated only for `provider: 'sandbox'` inboxes; null otherwise.
Show properties
Property Type Description
open_probability required number
click_probability required number
reply_probability required number
bounce_probability required number
open_delay_seconds_min required integer
open_delay_seconds_max required integer
click_delay_seconds_min required integer
click_delay_seconds_max required integer
reply_delay_seconds_min required integer
reply_delay_seconds_max required integer
Example response 
{
  "id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "object": "inbox",
  "mode": "live",
  "provider": "gmail",
  "email_address": "founder@acme.com",
  "display_name": "Alice from Acme",
  "status": "active",
  "status_reason": null,
  "daily_limit": 50,
  "effective_daily_limit": 26,
  "ramp": {
    "enabled": true,
    "start": 10,
    "end": 50,
    "days": 14,
    "started_at": "2026-04-22T09:00:00Z"
  },
  "signature_html": "<p>Alice<br>Acme</p>",
  "signature_text": "Alice\nAcme",
  "reply_to": null,
  "tags": [
    "outbound",
    "eu"
  ],
  "health_score": 92,
  "warmup_enabled": true,
  "timezone": "America/New_York",
  "last_send_at": "2026-04-29T14:32:11Z",
  "last_poll_at": "2026-04-29T15:00:04Z",
  "created_at": "2026-04-15T09:12:00Z",
  "revoked_at": null,
  "sandbox_config": null
}

Errors

  • 400 Invalid request
  • 401 Authentication failed
  • 403 Insufficient scope
  • 404 Not found
  • 409 Conflict
  • 422 Validation failed
  • 429 Rate limited

See Errors for the full envelope and per-code reference.