Message Ads API

Warning

Deprecation Notice: The Marketing Version 202510 (Marketing October 2025) will be sunset on October 15, 2026. We recommend that you migrate to the latest versioned APIs to avoid disruptions. For information on all the supported versions, refer to the migrations documentation. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Setup and manage message Ads via API to send direct messages via LinkedIn Messages to your prospects to spark immediate action. With message ads, you can engage your prospects through native ads displayed through LinkedIn Messaging.

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

A Message Ad is a message delivered to a LinkedIn member's InMail inbox. Message Ads provide a way for marketers to increase their reach on LinkedIn by sending personalized messages to the audiences that matter most to their business. Unlike InMail communications between members, a Message Ad is a branded message with a call-to-action button that takes the user to an advertiser's landing page. Lead Generation forms can also be attached to Message Ads. A target audience will see Message Ads as part of their messenger experience when they're active anywhere on the LinkedIn site, on desktop or mobile.

Prerequisites

  1. You have the Message Ads Campaign and Creative details under an Ad Account. For more information, see.

  2. Sender must have permission to send a Message Ad. To manage senders, see Manage Message Ad Senders.

Create a Message Ad

  1. Upload asset for Message Ad by following these steps.
  2. Create AdInMail Content for Message Ad.
  3. Create a draft message ad creative.
  4. Test the draft Message Ad.
  5. Make necessary modifications based on testing. Note: Creative should be in the DRAFT status.
  6. Activate the creative by updating the creative status to ACTIVE. The creative will be directed to the review queue after activation.

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.

    Note

    A "Not Interested" CTA is automatically included on Message Ads. The CTA is applied at render time and is not exposed in the API. Use test sends to preview the behavior.

    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 1,024 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 don't 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-restli-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

    Update the sender, subject, htmlBody, and subContent. Once a creative goes live, you can't 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

    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

    • Last updated on