Retrieve InMail History

The InMail History API allows you to retrieve InMail activity, both sent and received, that occurred on a given LinkedIn Recruiter contract. In order to properly store and associate these InMails within your application, you will need to already have retrieved the LinkedIn seat URN for the Recruiter seatholders and the member URN for the prospects.

It is recommended to make calls to this API on a periodic basis using a batch process. Set the time range to be no more than 12 hours per call, or more frequently as needed (e.g. every 30 minutes).

All API requests require authorization . Additionally, API requests return paged results; details on paging through results can be found here.

Note

Unlimited InMails can be sent to your 1st degree connection in your development environment provisioned by LinkedIn.

Throttle Limits

Throttle Limits	Requests Per Day (UTC)	Records Per member Per Minute
ConversationEvents maximum	100,000	12

API Endpoint

Retrieve message history between seat holders and prospects.

GET https://api.linkedin.com/v2/conversationEvents?q=criteria

API Request Parameters

Field	Description	Format	Required	Notes
viewer	The Recruiter seatholder	Seat URN in format urn:li:seat:{id}	Yes	Find InMails (sent and received) associated with a specific Recruiter Seatholder.
timeRange.start	Inclusive lower date boundary	Epoch in milliseconds (UTC)	No	Find InMails that were sent and received on or after a specific date.
timeRange.end	Exclusive upper date boundary	Epoch in milliseconds (UTC)	No	Find InMails that were sent and received before a specific date.

Sample Request

GET https://api.linkedin.com/v2/conversationEvents?q=criteria&viewer=urn:li:seat:123456789&timeRange.start=1486428734634

Response Body Field

The response will contain the list of events belonging to a conversation. Events have an author, a time that it was created and the mail content. Both private and public InMail messages associated with the viewer will be returned in this api call. The response body fields are described below.

Field	Description	Format	Required
author	The participant that created this event. If the mail is sent by the candidate this field will contain a Person URN else if the email is sent by the recruiter this field will contain a Recruiter seatholder URN.	Author URN will be in format urn:li:seat:{id} or urn:li:person:{id}	Yes
content	The content of this event, for example mail item with a subject and body.	MailContent	Yes
createdAt	Time when the event was created.	Epoch in Milliseconds (UTC)	Yes
id	The entity ID of the Event. It is a unique identifier for each InMail event	String	Yes
recipients	The list of all participants designated to receive this event. This field will contain the list of URNs.	String[]. Array will contain URNs in the format urn:li:seat:{id} or urn:li:person:{id}	Yes
threadUrn	The Thread identifier	Thread URN in the format urn:li:messagingThread:{id}	Yes

MailContent Schema

This defines the content of a mail item. It represents an item in the mail inbox.

Field	Description	Format	Required
body	The body of the mail. This field holds the content of the body in the text field as described in the sample response body below.	String	Yes
subject	The subject of the mail.	String	Yes

Sample Response Body

{
    "elements": [
        {
            "author": "urn:li:seat:123456789",
            "content": {
                "com.linkedin.messaging.events.MailContent": {
                    "body": {
                        "text": "Test response complete."
                    },
                    "subject": "RE: Testing Stub Profile"
                }
            },
            "createdAt": 1486428775129,
            "id": "I6234554148858486784_1000",
            "recipients": [
                "urn:li:person:a1b2c3d4d5"
            ],
            "threadUrn": "urn:li:messagingThread:6234532054298611712"
        },
        {
            "author": "urn:li:person:a1b2c3d4d5",
            "content": {
                "com.linkedin.messaging.events.MailContent": {
                    "body": {
                        "text": "Responding to test v2."
                    },
                    "subject": "RE: Testing Stub Profile"
                }
            },
            "createdAt": 1486428775229,
            "id": "I6234554148858486784_1000",
            "recipients": [
                "urn:li:seat:123456789"
            ],
            "threadUrn": "urn:li:messagingThread:6234532054298611712"
        },
        {
            "author": "urn:li:seat:123456789",
            "content": {
                "com.linkedin.messaging.events.MailContent": {
                    "body": {
                        "text": "Update test v2 complete."
                    },
                    "subject": "RE: Testing Stub Profile"
                }
            },
            "createdAt": 1486428775329,
            "id": "I6234544148858486784_1000",
            "recipients": [
                "urn:li:person:a1b2c3d4d5"
            ],
            "threadUrn": "urn:li:messagingThread:6234532054298611712"
        },
        {
            "author": "urn:li:person:a1b2c3d4d5",
            "content": {
                "com.linkedin.messaging.events.MailContent": {
                    "body": {
                        "text": "Test v2 complete."
                    },
                    "subject": "RE: Testing Stub Profile"
                }
            },
            "createdAt": 1486428775429,
            "id": "I6234534148858486784_1000",
            "recipients": [
                "urn:li:seat:123456789"
            ],
            "threadUrn": "urn:li:messagingThread:6234532054298611712"
        },
        {
            "author": "urn:li:seat:123456789",
            "content": {
                "com.linkedin.messaging.events.MailContent": {
                    "body": {
                        "text": "Dear testFirst, \n\nTesting Stub Profile v2\n\n"
                    },
                    "subject": "Testing Stub Profile"
                }
            },
            "createdAt": 1486428775529,
            "id": "S6234533985997901824_1000",
            "recipients": [
                "urn:li:person:a1b2c3d4e5"
            ],
            "threadUrn": "urn:li:messagingThread:6234532054298611712"
        }
    ],
    "paging": {
        "count": 5,
        "links": [
            {
                "href": "/v2/conversationEvents?count=5&q=criteria&start=5&viewer=urn%3Ali%3Aseat%3A123456789&timeRange.start=1486428734634",
                "rel": "next",
                "type": "application/json"
            }
        ],
        "start": 0,
        "total": 10
    }
}