Messaging Between Connections API

LinkedIn offers a simple API for sending messages via LinkedIn between two or more individuals connected to the member sending the message.

Usage

You must use an access token to make an authenticated call on behalf of a user

Permissions
This API requires the following permission (see Member Permissions)

Permission Description
w_messages Required to send messages to connections on behalf of authenticated user

Throttle Limits
Please reference the limits applied to this API

Requirements

You must adhere to the following requirements when posting a message with LinkedIn:

  • A message between connections must be associated with a specific user action, not an automated or scheduled event. A user simply navigating through your application is not a significant event.
  • The user must be given a choice about whether to send the message. The user must opt into the messages being sent rather than opt out.
  • The user must be presented with the exact body and subject of the message and have the opportunity to customize both the subject and the body. Pre-prepared messages are allowed only if the user has full control over what is ultimately posted on their behalf.
  • A message between connections must come at or around the time the user took action to send the message.
  • An application must not offer any direct incentive to the user as a reward for issuing a message between connections.
  • An application must not offer any direct incentive to the recipients of a message between connections.
  • Messages posted on LinkedIn must not contain any HTML.

A 201 Created HTTP status indicates successful creation of a message.

Format

This API resource can be accessed using JSON or XML.  Examples are provided in both formats.  When using JSON you will need to send the Content-Type header to "application/json".

Messaging XML POST Body Structure

Node Parent Node Required? Notes
mailbox-item yes Top-level containing element for a message
recipients mailbox-item yes Containing element for one or more recipient elements.
recipient recipients at least one An intended recipient of the message who is directly connected to the poster.
person recipient one and only one person per recipient You must include a path attribute indicating the recipient. For example, if one recipient was a member identified by the id "abcdefg", the path attribute would equal "/people/abcdefg". To make the sender a recipient, include a recipient with the tilde notation: "/people/~"
subject mailbox-item yes The subject of the message. Must be editable by the member sending the message.
body mailbox-item yes The body of the message. Cannot contain HTML. Must be editable by the member sending the message.

Example Messaging XML POST Body

In this example, we are sending a message to the sender as well as a single connection.

<?xml version='1.0' encoding='UTF-8'?>
<mailbox-item>
<recipients>
<recipient>
<person path='/people/~'/>
</recipient>
<recipient>
<person path="/people/abcdefg" />
</recipient>
</recipients>
<subject>Congratulations on your new position.</subject>
<body>You're certainly the best person for the job!</body>
</mailbox-item>

Example Messaging JSON POST Body

In this example, we are sending a message to the sender as well as a single connection.

{
  "recipients": {
    "values": [
    {
      "person": {
        "_path": "/people/~"
       }
    },
    {
      "person": {
        "_path": "/people/abcdefg"
       }
    }]
  },
  "subject": "Congratulations on your new position.",
  "body": "You are certainly the best person for the job!"
}