Skip to main content
The inbox holds the conversations of your sending accounts: the email threads of your mailboxes and the LinkedIn chats of your seats. A mailbox’s existing mail comes in from the moment it connects, not only the replies to your campaigns. You can read conversations, mark, star, archive and label them, reply, start new ones, and invite people to connect on LinkedIn. Every inbox call is free.

List conversations

Every list is of one channel, so channel is required: email or linkedin. A call without it answers 422.
Conversations come newest first. Narrow them with: 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’s channel with it:
Messages come oldest first. An email message carries its sender, recipients, subject, HTML body, labels and attachment names, and its 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, isSpam and isDeleted each move the conversation, and a call takes only one of them: two answer 422.
  • A label needs an email received. A conversation with none answers 422 conversation_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 isRead true.
  • 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:
Each conversation comes back, in the order sent, with a 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, inReplyToMessageId or the newest, in the same thread and under the same subject, with any cc and bcc. 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-Key with every try, and the reply goes out once. See Idempotency.
  • When it is refused, nothing is sent: 422 recipient_unsubscribed when the recipient unsubscribed from the mailbox’s emails, 422 mailbox_needs_reconnect when the mailbox’s sign-in lapsed, 404 message_not_found when inReplyToMessageId is 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 its status is scheduled. Closing your organization cancels the scheduled emails that have not gone out, and reopening it does not bring them back.
  • from is one of your mailboxes, as GET /v1/accounts?channel=email lists it. One you do not have answers 404 account_not_found.
  • It uses one of the mailbox’s emails for the day, and cannot be taken back.

A LinkedIn message

A LinkedIn message goes from one of your seats, 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: 409 linkedin_invitation_already_sent. One past the seat’s allowance answers 422 linkedin_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: 403 linkedin_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.