List conversations
Every list is of one channel, sochannel is required: email or linkedin. A call without it answers 422.
For the next page, send
pagination.nextCursor as cursor, with the same filters. See Pagination.
Count conversations
GET /v1/conversations/counts answers how many email conversations each folder holds. folders picks the folders, separated by commas, and mailbox the mailboxes:
unread counts the conversations with an email not yet read. On LinkedIn, the unread count is the pagination.total of GET /v1/conversations?channel=linkedin&folder=unread&pageSize=1.
Read a conversation
Send the conversation’schannel with it:
messageId, which a reply takes as inReplyToMessageId. A LinkedIn message carries its text, its sender and when it was sent. A conversation your organization does not have answers 404 conversation_not_found.
Mark, star, archive and label
PATCH /v1/conversations/{conversationId} changes one conversation. Send its channel and the changes:
- Changes reach the mail provider too, so the mailbox itself shows them. Each takes 2 to 5 seconds.
- One move a call.
isArchived,isSpamandisDeletedeach move the conversation, and a call takes only one of them: two answer422. - A label needs an email received. A conversation with none answers
422conversation_has_no_received_email. - Back to the inbox means the inbox: taking a conversation out of Archived puts it in the inbox, even one that was only in Sent.
- A LinkedIn chat can only be marked read, with
isReadtrue. - Changes have their own limit: 30 a minute and 1,000 a day.
Change many at once
PATCH /v1/conversations makes one change to 1 to 50 email conversations:
status: updated, not_found, too_large (more emails than one change can touch), needs_reconnect (its mailbox must be connected again) or failed. An id your organization does not have is not_found, not an error. LinkedIn chats change one at a time. Bulk changes have their own limit: 20 a minute and 300 a day.
Reply
- An email reply goes from the conversation’s mailbox to the sender of the message it answers,
inReplyToMessageIdor the newest, in the same thread and under the same subject, with anyccandbcc. Write it in HTML, with each paragraph in a<p>. - A LinkedIn reply is a message in the chat, in plain text, up to 8,000 characters.
- It goes at once, and cannot be taken back. An email reply uses one of the mailbox’s emails for the day.
- Retrying is safe with a key. Send the same
Idempotency-Keywith every try, and the reply goes out once. See Idempotency. - When it is refused, nothing is sent:
422recipient_unsubscribedwhen the recipient unsubscribed from the mailbox’s emails,422mailbox_needs_reconnectwhen the mailbox’s sign-in lapsed,404message_not_foundwheninReplyToMessageIdis not in the conversation.
Start a new conversation
An email
POST /v1/messages sends an email from one of your mailboxes, from, to 1 to 50 recipients:
- It goes at once, unless you send
scheduledAt: then it waits until that time, and itsstatusisscheduled. Closing your organization cancels the scheduled emails that have not gone out, and reopening it does not bring them back. fromis one of your mailboxes, asGET /v1/accounts?channel=emaillists it. One you do not have answers404account_not_found.- It uses one of the mailbox’s emails for the day, and cannot be taken back.
A LinkedIn message
accountId, to a connection of the seat, in plain text. With "inMail": true, and a subject if you like, it goes as an InMail instead: it reaches someone the seat is not connected to, and spends one of the seat’s InMail credits. InMail needs a Premium, Sales Navigator or Recruiter seat: any other answers 422 linkedin_inmail_not_available.
Invite someone on LinkedIn
- The note is optional, up to 200 characters.
- LinkedIn refuses a second invitation to someone the seat invited recently:
409linkedin_invitation_already_sent. One past the seat’s allowance answers422linkedin_invitation_limit_reached. - A seat’s allowances are set on the seat: see Connect sending accounts.
Keys and limits
- Keys. The inbox comes with the campaigns scope. Read-only keys can list, count and read conversations. Changes and sends need a key that can write. A LinkedIn seat that may be used in campaigns only cannot be read or sent from here:
403linkedin_permission_denied. - Rate limits. Reading conversations and their counts: 60 calls a minute and 5,000 a day. Changing one conversation: 30 a minute and 1,000 a day. Bulk changes: 20 a minute and 300 a day. Replies, new messages and invitations share one more: 20 a minute and 600 a day. Each mailbox and seat also keeps its own daily allowance. See Rate limits.