Senders

A sender is a person your campaigns speak as. It groups that person's accounts: one LinkedIn account at most, and any number of mailboxes and WhatsApp numbers. In a campaign, a lead then hears from one sender on every channel: its LinkedIn messages, its emails and its WhatsApp messages all come from the same person.

Senders are optional. Until an account belongs to a sender, campaigns assign each channel on its own, exactly as before.

In Swarmhit, senders are on the Accounts page, By sender.

The Sender accounts endpoints, and operations such as connectSender, pauseSender or rebalanceCampaignSender, act on LinkedIn accounts, not on these senders.

Creating a sender

POST /senders creates one, with its accounts if you have them:

curl -X POST https://app.swarmhit.com/api/v1/senders \
  -H "Authorization: Bearer swh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maya",
    "lastName": "Chen",
    "managerIds": ["uSr9Km2Lp4Qx"],
    "linkedinAccountId": "sN4Xq7Lm2Rw9Zk5Yp",
    "emailAccountIds": ["mBx4Qw8RmZk2Yp5Ns", "mBx7Tr2PqLm9Wx3Kd"]
  }'

{
  "data": {
    "id": "sDr8Lq2Mw5Xk9Pz3",
    "firstName": "Maya",
    "lastName": "Chen",
    "name": "Maya Chen",
    "picture": "https://cdn.swarmhit.com/p/maya.jpg",
    "managerIds": ["uSr9Km2Lp4Qx"],
    "linkedinAccountId": "sN4Xq7Lm2Rw9Zk5Yp",
    "emailAccountIds": ["mBx4Qw8RmZk2Yp5Ns", "mBx7Tr2PqLm9Wx3Kd"],
    "whatsappAccountIds": [],
    "createdAt": "2026-11-06T10:12:00.000Z",
    "updatedAt": "2026-11-06T10:12:00.000Z"
  }
}

• firstName and lastName fill {{senderFirstName}}, {{senderLastName}} and {{senderFullName}} in every message its accounts send, on every channel. An account with no sender keeps reading its own name: the LinkedIn profile's, the mailbox's From name, the WhatsApp profile's.
• managerIds are workspace members who manage the sender: they get its account alerts in Swarmhit and can narrow the inbox, campaigns, tasks and dashboard to the senders they manage. Every member still sees every sender.
• picture comes from its accounts: the LinkedIn photo, else a mailbox's or a number's.

GET /senders lists them, GET /senders/{id} reads one, and DELETE /senders/{id} deletes one: its accounts stay connected and stay in their campaigns, without a sender.

Linking accounts

An account belongs to one sender at most. Link it from either side:

• PATCH /senders/{id} with linkedinAccountId, emailAccountIds or whatsappAccountIds. A list replaces that kind of account: accounts left out lose this sender, and an account listed here leaves the sender it had. linkedinAccountId: null unlinks its LinkedIn account.
• senderId (a sender id, or null) on PATCH /accounts/{id}, PATCH /email-accounts/{id} or PATCH /whatsapp-accounts/{id}. Linking a LinkedIn account to a sender that already has one is refused (400, code: sender-has-linkedin).

Every account object carries its senderId. Linking a mailbox or WhatsApp number adds it to the campaigns its sender sends in (below) whose sequence uses its channel; a LinkedIn account is never added this way. Unlinking never takes an account out of a campaign.

In campaigns

A campaign's senderIds lists the senders that send in it: those with an account on its primary channel (below), or in any pool while the sequence has no sending step. Set it with createCampaign or updateCampaign: a sender added brings its accounts on the channels the sequence uses, and one removed takes its accounts out of the pools (an account still carrying another sender's conversation stays). A pool you send in the same request (linkedinAccountIds, emailAccountIds, whatsappAccountIds) keeps exactly what you send. A sequence that starts using a channel takes its senders' accounts on that channel.

How leads are spread once accounts belong to senders:

• The campaign's primary channel is LinkedIn when its sequence has a LinkedIn step, else email, else WhatsApp. Leads are spread over its accounts as before, and that account names the lead's sender.
• On each other channel whose pool holds an account with a sender, a lead gets one of its sender's own accounts there, spread evenly (by provider within them with matchEmailProvider).
• When none of them can send (paused, warming up, offline, disconnected), the sender's leads wait at those steps. They never move to another sender's account. The campaign keeps sending for the other senders, and its notice says it is partly on hold.
• A lead whose sender has no account on that channel, or whose primary account has no sender, shares the pool's accounts that have no sender. With none, it waits at those steps.
• An account whose sender doesn't send in the campaign takes no new lead there: it only carries on the conversations it has.
• A lead that already has a conversation keeps its mailbox or number, and so does a lead whose primary account has left the campaign. Pools in which no account has a sender work exactly as before.

On each lead in a campaign, senderId is its sender, or null.

Activating a campaign, or changing the pools or the sequence of an active one, is refused with 400 and code: sender-no-mailbox (or sender-no-whatsapp) when a sender in it, or an account without a sender on its primary channel, has no account on a channel its steps use, and no account without a sender is there to share. On an active campaign, only a change that opens such a gap is refused: one opened by linking accounts leaves its other changes working, while the leads concerned wait.

Adding a sender with senderIds is refused with 400 when it can't send in the campaign:

• sender-no-account: it has no account on any channel the sequence uses.
• sender-without-linkedin (sender-without-email, sender-without-whatsapp for a campaign whose primary channel is email or WhatsApp): it has no account on the primary channel.

Inbox and webhooks

Inbox chats carry the senderId of their account, and GET /inbox/chats?senderId= lists the chats of every account of one sender. Every webhook payload with an accountId also has senderId, the account's sender at the time of the event, or null.