Skip to main content
POST
Add a sender

Authorizations

X-API-Key
string
header
required

Body

application/json

A sender is a person, so a person's name is all it takes to create one.

The workspace-unique display name is derived from these two. There is no separate name to type, and therefore no way for it to disagree with the first and last name the messages themselves are signed with.

first_name
string
required

The sender's first name.

Required string length: 1 - 128
last_name
string
default:""

The sender's last name.

Maximum string length: 128
signature_text
string
default:""

Plain-text signature appended to every send as this profile.

timezone
string | null

The creating browser's IANA timezone, kept as a guess that only a person changes after. One this server does not know is dropped.

Maximum string length: 64

Response

Successful Response

booking_url
string | null
required

The link people use to book a meeting with this sender, such as a Calendly or Cal.com page. It is what the {{Sender booking link}} variable is replaced with. Null when none is set.

created_at
string<date-time>
required
id
string<uuid>
required
mailbox_count
integer
required
name
string
required
send_mode
enum<string>
required

Whether the messages the agent writes for this sender go out on their own or wait for a person, replies included. Always send (always_send): every message the agent writes goes out on its own. Send when confident (send_when_confident, the default): a message goes out when the agent rates its own message high and had enough data, and waits for a person otherwise. Always ask (always_ask): a person approves every one. A sequence set to ask first still asks, whichever mode its senders are on.

Available options:
always_send,
send_when_confident,
always_ask
status
enum<string>
required

Lifecycle of a sender.

A sender is DRAFT from the moment it is created and becomes ACTIVE once at least one mailbox is attached. The status is derived from attachment, never stored, so it cannot drift.

Available options:
draft,
active
title
string
required

The sender's job title, as their messages introduce them. It is what the {{Sender title}} variable is replaced with. Empty when none is set.

updated_at
string<date-time>
required
daily_limit
integer
default:0
email_approval_mode
enum<string> | null

manual | auto; null inherits the workspace's email approval mode.

Available options:
manual,
auto
first_name
string
default:""
last_name
string
default:""
linkedin_checkpoint
boolean
default:false

True while LinkedIn is asking this sender to verify the account.

linkedin_connection_request_cap
integer
default:0
linkedin_connection_requests_today
integer
default:0
linkedin_identity
string | null
linkedin_last_seen_at
string<date-time> | null

When a browser for this sender last checked in.

linkedin_photo_url
string | null
linkedin_presence
enum<string> | null

How recently ANY browser connected to this sender checked in.

Three states, not two, because two different questions are asked of a connection. ACTIVE answers "can a step run right now": a browser is open and heartbeating. IDLE answers "is this still set up": the laptop was closed for the evening. NOT_SEEN is the one that needs a person: nothing has checked in for a day, and queued work is silently waiting.

Available options:
active,
idle,
not_seen
linkedin_run_mode
enum<string> | null

The sender's LinkedIn approval setting in force: manual (a person approves each step on Tasks before it runs) or auto. Null when no LinkedIn account is connected.

Available options:
manual,
auto
linkedin_usage
SenderLinkedInUsageSchema · object[]

Today's LinkedIn steps against each kind's daily limit.

sent_today
integer
default:0
signature_text
string
default:""
timezone
string | null

The sender's IANA timezone, such as America/New_York. Their daily limits reset at its midnight, and a sequence sending in each sender's timezone sends in its hours. Null until it is detected or chosen.

timezone_source
enum<string> | null

Where the timezone came from: guessed from whoever created the sender or the sequences it sent for, browser from the browser driving the sender's LinkedIn when the sender had none, person chosen by someone. Detection only fills an empty timezone and never moves one a sender has.

Available options:
guessed,
browser,
person