Share via

Message Ads API

  • Article

Warning

Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

You can setup and manage message Ad InMail contents sent to targeted LinkedIn members’ inbox, either as a Message Ad or a Conversation Ad.

This API replaces the previous /adInMailContentsV2 and /adInMailContents APIs.

Permissions

Permission Possible Values
rw_ads Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
    		•
    r_ads Read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
    		•

    See Account Access Controls for more information on company page roles.

    Schema

    InMail Content

    Note

    Starting 202410, a new name field is introduced in Creative schema. Going forward, this new name field is the preferred approach to set and get the creative's name, consistently across all ad formats. The current name field in InMail Content schema is still supported for the time being for Message ads. The creative's name is pre-populated using the legacy value.

    Field Type Details Required
    id AdInMailContent URN Unique ID of the InMail content (Read-Only) Yes
    account SponsoredAccount URN Advertising account URN that the content is associated with. For example, urn:li:sponsoredAccount:12121 Yes
    name string Canonical name of the content Yes
    sender URN The sender from whom the Sponsored InMail was sent from. Used to render the sender in detail and list views. The sender can be either a Person URN or an Organization URN. Yes
    subject string The subject of the content. Displayed in the inbox’s list and detailed view. Yes
    htmlBody string Raw HTML body text for the content. No
    customFooter string The terms and conditions of the content. Shown on the bottom of the message. No
    subContent AdInMailRegularSubContent, AdInMailGuidedRepliesSubContent, or AdInMailFormSubContent, The subcontent, which will be one of several types depending on the advertiser’s objective. Yes
    lastModifiedAt Time Time at which the content was last modified in milliseconds since epoch (Read-Only) Yes
    lastModifiedBy URN The entity (e.g. Person URN) who most recently modified the content. (Read-Only) Yes
    createdAt Time Time at which the content was created (Read-Only) Yes
    createdBy URN The entity (e.g. person URN) who created this content (Read-Only) Yes

    AdInMailRegularSubContent

    Field Type Details Required
    callToActionText string The text for the call-to-action button. Max length of 20 characters. Yes
    callToActionLandingPage URL The landing page’s URL. The call-to-action button redirects to this URL. Max length of 1024 characters. Yes
    rightRailAdPicture Image URN The picture to be displayed on the right-rail ad space with this Sponsored InMail No

    AdInMailGuidedRepliesSubContent

    Field Type Details Required
    sponsoredConversation SponsoredConversation URN URN of the guided replies conversation which contains contents of all the messages. Yes
    rightRailAdPicture Image URN The picture to be displayed on the right-rail ad space within the detail view. No

    AdInMailFormSubContent

    Field Type Details Required
    callToActionText string The text for the call-to-action button that redirects to a lead generation form. Max length of 20 characters. Yes
    rightRailAdPicture Image URN The picture to be displayed on the right-rail ad space within the detail view. No

    Note: InMails associated with a leadGen Form do not have a landing Page URL since the landing Page is determined by the lead gen form. Please use the landingPage field in the adForms API to set or update landing pages for InMails that have AdInMailFormSubContent.

    Create InMail Content

    Regular

    POST https://api.linkedin.com/rest/inMailContents/

    {
 "account": "urn:li:sponsoredAccount:508915158",
 "name": "test strings",
 "subject": "test subject",
 "sender": "urn:li:person:12345",
 "customFooter": "terms and conditions",
 "htmlBody":"sample body",
 "subContent": {
   "regular": {
     "callToActionText": "sample string",
     "callToActionLandingPageUrl":"http://www.linkedin.com",
     "rightRailAdPicture": "urn:li:image:C5F22AQFIMShx0jJbQw"
   }
 }
}

    Guided Conversation

    POST https://api.linkedin.com/rest/inMailContents/

    {
 "account": "urn:li:sponsoredAccount:508915158",
 "name": "test strings",
 "subject": "test subject",
 "sender": "urn:li:person:12345",
 "customFooter": "terms and conditions",
 "htmlBody":"sample body",
 "subContent": {
   "guidedReplies": {
     "sponsoredConversation": "urn:li:sponsoredConversation:1641954",
     "rightRailAdPicture": "urn:li:image:C4D10AQHMsMTTjxlblw"
   }
 }
}

    LeadGen Form

    POST https://api.linkedin.com/rest/inMailContents/

    {
 "account": "urn:li:sponsoredAccount:508915158",
 "name": "test strings",
 "subject": "test subject",
 "sender": "urn:li:person:12345",
 "customFooter": "terms and conditions",
 "htmlBody":"sample body",
 "subContent": {
   "form": {
     "callToActionText": "sample string",
     "rightRailAdPicture": "urn:li:image:C5F22AQFIMShx0jJbQw"
   }
 }
}

    A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header.

    Get InMail Content

    Retrieve InMail Content while passing in an AdInMailContent URN into {adInMailContentURN}. Example below shows a GET request and response for regular sub-content.

    GET https://api.linkedin.com/rest/inMailContents/{adInMailContentURN}

    Sample Request

    GET https://api.linkedin.com/rest/inMailContents/urn:li:adInMailContent:6684124

    Sample Response

    {
   "createdAt": 1649351278000,
   "htmlBody": "sample body",
   "lastModifiedAt": 1649351278000,
   "sender": "urn:li:person:B1U4S2MZ-C",
   "createdBy": "urn:li:person:12344",
   "subject": "test subject",
   "lastModifiedBy": "urn:li:person:12344",
   "name": "test strings",
   "customFooter": "terms and conditions",
   "id": "urn:li:adInMailContent:6674504",
   "account": "urn:li:sponsoredAccount:508915158",
   "subContent": {
       "regular": {
           "rightRailAdPicture": "urn:li:image:C5F22AQFIMShx0jJbQw",
           "callToActionLandingPageUrl": "http://www.linkedin.com",
           "callToActionText": "sample string"
       }
   }
}

    Update InMail Content

    You can update the sender, subject, htmlBody, and subContent. Once a creative goes live, you cannot modify it further.

    In the following example, the name field is changed.

    Sample Request

    POST https://api.linkedin.com/rest/inMailContents/urn:li:adInMailContent:6684124

    {
 "patch": {
   "$set": {
     "name": "test strings new"
   }
 }
}

    Sample Response

    A successful response returns a 204 No Content HTTP status code.

    Batch Get InMail Content

    You can also fetch multiple Message Ad records by providing multiple IDs.

    GET https://api.linkedin.com/rest/inMailContents?ids={encoded adInMailContentId}&ids={encoded adInMailContentId}

    Sample Response

    {
   "results": {
       "urn:li:adInMailContent:6674504": {
           "createdAt": 1649351278000,
           "htmlBody": "sample body",
           "lastModifiedAt": 1649351278000,
           "sender": "urn:li:person:B1U4S2MZ-C",
           "createdBy": "urn:li:person:12344",
           "subject": "test subject",
           "lastModifiedBy": "urn:li:person:12344",
           "name": "test strings",
           "customFooter": "terms and conditions",
           "id": "urn:li:adInMailContent:6674504",
           "account": "urn:li:sponsoredAccount:508915158",
           "subContent": {
               "regular": {
                   "rightRailAdPicture": "urn:li:image:C5F22AQFIMShx0jJbQw",
                   "callToActionLandingPageUrl": "http://www.linkedin.com",
                   "callToActionText": "sample string"
               }
           }
       },
       "urn:li:adInMailContent:5122946": {
           "createdAt": 1650404673000,
           "htmlBody": "sample body",
           "lastModifiedAt": 1650404673000,
           "sender": "urn:li:person:B1U4S2MZ-C",
           "createdBy": "urn:li:person:12344",
           "subject": "test subject",
           "lastModifiedBy": "urn:li:person:12344",
           "name": "test strings",
           "customFooter": "terms and conditions",
           "id": "urn:li:adInMailContent:5122946",
           "account": "urn:li:sponsoredAccount:508915158",
           "subContent": {
               "regular": {
                   "rightRailAdPicture": "urn:li:image:C5F22AQFIMShx0jJbQw",
                   "callToActionLandingPageUrl": "http://www.linkedin.com",
                   "callToActionText": "sample string"
               }
           }
       }
   },
   "statuses": {
       "urn:li:adInMailContent:6674504": 200,
       "urn:li:adInMailContent:5122946": 200
   },
   "errors": {}
}

    Send Test InMail

    The sendTestInMail action can be used to trigger a test message for a draft message or conversation ad. The recipient will be the same as the authenticated LinkedIn member and the test message can be viewed in the recipient’s LinkedIn inbox.

    POST https://api.linkedin.com/rest/inMailContents?action=sendTestInMail

    {
  "adInMailContentId": "urn:li:adInMailContent:5118806",
  "campaign": "urn:li:sponsoredCampaign:194467334",
  "creative": "urn:li:sponsoredCreative:170358284",
  "account": "urn:li:sponsoredAccount:508915158"
}

    A successful response returns a 200 OK HTTP status code.

    References