Ad InMail Contents

You can set up the message contents sent to targeted LinkedIn members' inbox, either as a Message Ad or a Conversation Ad.

Permissions

Permission Description
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 ad account roles.

    Schemas

    AdInMailContents

    Field Type Description
    account SponsoredAccountUrn The immutable advertising account's URN identifier that the content is associated with. For example, urn:li:sponsoredAccount:12121.
    htmlBody optional string Raw HTML body text.
    legalText.rawText optional string The content's text legal terms and custom conditions. Specified by the advertiser.
    editable boolean, default="true" Flag that specifies if adInMailContent is editable. Starting July 2021 this field will not be set to false by our systems and will be deprecated in the future.
    id long The ID of the InMail content.
    name string The canonical name for this content. Used to conveniently refer to the content. Specified by the advertiser.
    sender AdInMailSender The content's sender information. Used to render the sender in the detail and list view. Also used for various security checks. Specified by the advertiser.
    subContent AdInMailStandardSubContent, AdInMailFormSubContent, or AdInMailGuidedRepliesSubContent The content's subcontent; the subcontent is one of several types depending on the advertiser's objective.
    subject string The content's text subject. The subject is displayed in both the list and detail view of the inbox as specified by the advertiser.
    changeAuditStamps read-only changeAuditStamps Audit changed stamps including created timestamp and last updated timestamp.

    AdInMailStandardSubContent or AdInMailFormSubContent

    Field Type description
    action Url The landing page's URL. The call-to-action button redirects to the URL as specified by the advertiser:
  • AdInMailStandardSubContent - redirects to the landing page URL
  • AdInMailFormSubContent - redirects to the LGF
  • actionText string The text on the call-to-action button as specified by the advertiser.
    adUnitV2 Optional DigitalMediaAssetUrn Upload Media Asset The ad to be displayed on the right-rail ad space with this Message Ad as specified by the advertiser. For example, urn:li:digitalmediaAsset:kjdhsdf.

    AdInMailStandardSubContent or AdInMailFormSubContent

    AdInMailGuidedRepliesSubContent

    Field Type Description
    sponsoredConversation com.linkedin.common.SponsoredConversationUrn URN of the SponsoredConversation conversation. Conversation contains contents of all the messages.
    rightRailAdPicture com.linkedin.common.DigitalmediaAssetUrn The picture to be displayed on the right-rail ad space within the detail view. Specified by the advertiser.

    AdInMailLeadGenSubContent Deprecated

    Field Type Description
    actionText string The text on the call-to-action button. Specified by the advertiser.
    afterActiontext Optional string The text to show after the action button is clicked. Specified by the advertiser.
    adUnitV2 Optional DigitalMediaAssetUrn Upload Media Asset The ad to be displayed on the right-rail ad space with this Message Ad. Specified by the advertiser. For example, urn:li:digitalmediaAsset:kjdhsdf.

    AdInMailSender

    Field Type Description
    displayName Optional string The display name is a customized name for the sender. If specified, it overrides the from entity's name during rendering. Specified by the advertiser.
    displayPicture MediaUrn Deprecated The display picture is a customized picture URN. If specified, it overrides the from entity's picture during rendering. Specified by the advertiser. For example, urn:li:media:121212jkhkhh.jpg.
    from Optional urn The sender's entity identifier. The from field displays from whom the message was sent. The from field can be a person URN or organization URN. If the alternate image and name are not specified, the current profile information relating to the URN is used. Specified by the advertiser. For example, urn:li:person:K1RwyVsdfsdNukt.
    senderType.AdInMailSenderType string The sender's type can be as follows, "MEMBER", "COMPANY", "CUSTOM_MEMBER", "CUSTOM_COMPANY". "MEMBER" is the default.
    displayPictureV2 optional DigitalmediaAssetUrn The display picture to be shown on the message. If specified, it overrides the from entity's picture during rendering. Specified by the advertiser. The note below describes how you can resolve a DigitalmediaAssetUrn.

    To resolve the urn:li:digitalmediaAsset:<id>, you can use projections. The response returns a number of URLs that you can chose at runtime based on your use case. Use the projection=(subContent(com.linkedin.ads.AdInMailStandardSubContent(adUnitV2~:playableStreams))) projection syntax to resolve the URN.

    Note

    Dynamic expansions of first name and last name fields are supported in htmlBody. Use %FIRSTNAME% and %LASTNAME% to specify first name and last name respectively.

    Managing AdInMailContent

    Create AdInMailContent

    POST https://api.linkedin.com/v2/adInMailContentsV2
    
    {
        "account": "urn:li:sponsoredAccount:516413367",
        "legalText": {
            "rawText": "Legal Text"
        },
        "htmlBody": "<p>In Mail text goes here</p>",
        "name": "Sponsored In Mail content Name",
        "sender": {
            "from": "urn:li:person:K1RwyVNukt"
        },
        "subContent": {
            "com.linkedin.ads.AdInMailStandardSubContent": {
                "action": "http://landingPageUrlOnAction.com/checkoutcart",
                "actionText": "Buy (Call to action text)",
                "adUnitV2": "urn:li:digitalmediaAsset:C5F0CAQGAq0elyqCQGQ"
            }
        },
        "subject": "Subject text "
    }
    

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

    Note

    When creating or updating the Message Ads Content, only the "sender.from" parameter can be used to set a sender. Other AdInMailSender parameters are ignored.

    Update AdInMailContent

    sender, subject, htmlBody, and subContent can be updated if the editable field of the content is true. Once a creative goes live, the editable flag changes to false automatically.

    Sample Request

    In the following example, the name field is changed.

    POST https://api.linkedin.com/v2/adInMailContentsV2/{adInMailContentId}
    
    {
        "patch": {
            "$set": {
                "name": "New Sponsored In Mail Ad content Name"
            }
        }
    }
    

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

    Note

    When creating or updating Message Ads Content, only the "sender.from" parameter can be used to set a sender. Other AdInMailSender parameters are ignored.

    Get AdInMailContent

    GET https://api.linkedin.com/v2/adInMailContentsV2/{adInMailContentId}
    

    Sample Response

    {
        "account": "urn:li:sponsoredAccount:516413367",
        "changeAuditStamps": {
            "created": {
                "actor": "urn:li:person:K1RwyVNukt",
                "time": 1512668766000
            },
            "lastModified": {
                "actor": "urn:li:unknown:0",
                "time": 1512668766000
            }
        },
        "htmlBody": "<p>In Mail text goes here</p>",
        "id": 691774,
        "name": "Sponsored In Mail content Name",
        "sender": {
            "displayName": "Pooja N",
            "displayPictureV2": "urn:li:digitalmediaAsset:C5500ABHmLDGaq51Fqg",
            "from": "urn:li:person:K1RwyVNukt"
        },
        "subContent": {
            "com.linkedin.ads.AdInMailStandardSubContent": {
                "action": "http://landingPageUrlOnAction.com/checkoutcart",
                "actionText": "Buy (Call to action text)",
                "adUnitV2": "urn:li:digitalmediaAsset:C5F0CAQGAq0elyqCQGQ"
            }
        },
        "subject": "Subject text "
    }
    

    Batch Get

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

    Sample Request

    GET https://api.linkedin.com/v2/adInMailContentsV2?ids=656344&ids=644954
    

    Sample Response

    {
        "errors": {},
        "results": {
            "644954": {
                "account": "urn:li:sponsoredAccount:516413367",
                "changeAuditStamps": {
                    "created": {
                        "actor": "urn:li:person:K1RwyVNukt",
                        "time": 1500409543000
                    },
                    "lastModified": {
                        "actor": "urn:li:unknown:0",
                        "time": 1501801043000
                    }
                },
                "editable": true,
                "htmlBody": "<p>Dear&nbsp;%FIRSTNAME%,</p><p>You can format the text as follows-</p><p><em>Italicized&nbsp;</em><strong>Bold&nbsp;</strong><u>Underlined</u></p><p><span>You can have bullet list as follows-</span></p><li>Bullet1<li>Bullet2<p>You can have href link as follows-</p><p>Link =&nbsp;<a href=\"http://api.linkedin.com\" target=\"_blank\">API doc</a></p><p>You can also have numbered list as follows-</p><ol><li>Point 1<li>Point 2</ol><p>&nbsp;</p><p>Cheers,&nbsp;</p><p>Linkedin Team</p><p>&nbsp;</p>",
                "id": 644954,
                "name": "New Sponsored In Mail Ad content Name",
                "sender": {
                    "displayName": "Pooja N",
                    "displayPictureV2": "urn:li:digitalmediaAsset:C5500ABHmLDGaq51Fqg",
                    "from": "urn:li:person:K1RwyVNukt"
                },
                "subContent": {
                    "com.linkedin.ads.AdInMailStandardSubContent": {
                        "action": "http://api.linkedin.com",
                        "actionText": "Click here",
                        "adUnitV2": "urn:li:digitalmediaAsset:C5F0CAQGAq0elyqCQGQ"
                    }
                },
                "subject": "InMail Subject on EI Edit1"
            },
            "656344": {
                "account": "urn:li:sponsoredAccount:516413367",
                "changeAuditStamps": {
                    "created": {
                        "actor": "urn:li:person:K1RwyVNukt",
                        "time": 1501708735000
                    },
                    "lastModified": {
                        "actor": "urn:li:unknown:0",
                        "time": 1501708735000
                    }
                },
                "htmlBody": "In Mail goes here",
                "id": 656344,
                "name": "Sponsored In Mail content Name",
                "sender": {
                    "displayName": "Pooja N",
                    "displayPictureV2": "urn:li:digitalmediaAsset:C5500ABHmLDGaq51Fqg",
                    "from": "urn:li:person:K1RwyVNukt"
                },
                "subContent": {
                    "com.linkedin.ads.AdInMailStandardSubContent": {
                        "action": "http://landingPageUrlOnAction.com/checkoutcart",
                        "actionText": "Buy (Call to action text)",
                        "adUnitV2": "urn:li:digitalmediaAsset:C5F0CAQGAq0elyqCQGQ"
                    }
                },
                "subject": "Subject text "
            }
        },
        "statuses": {}
    }
    

    Managing Sender Permissions

    As a LinkedIn Ad Account manager, you can manage senders for Message or Conversation Ads you've created.

    Please refer to Senders for Message and Conversation Ads for more details.

    Upload Message Ads Asset

    To upload an asset for a Message Ad, first register the upload. The register upload call returns a URL to which you can upload the asset. See Media Assets for more details.

    Register an Upload

    To register an upload for a Message Ad, set the recipes array to contain "urn:li:digitalmediaRecipe:spinmail-banner-image".

    POST https://api.linkedin.com/v2/assets?action=registerUpload
    
    {
        "registerUploadRequest": {
            "owner": "urn:li:organization:5025865",
            "recipes": [
                "urn:li:digitalmediaRecipe:spinmail-banner-image"
            ],
            "serviceRelationships": [
                {
                    "identifier": "urn:li:userGeneratedContent",
                    "relationshipType": "OWNER"
                }
            ]
        }
    }
    

    Upload Sponsored InMail Asset

    To upload a Sponsored InMail asset, use the upload request from the response body, as shown in Vector Asset. For SpinMail upload, you must also pass your authorization token.

    curl -v -H 'Authorization: Bearer <TOKEN>' --upload-file /Users/foo/Downloads/sample_img.jpg "https://api.linkedin.com/mediaUpload/C540CAQHP7zcjcbiaHg/spinmail-banner-uploadedImage/0?ca=vector_spinmail&cn=uploads&m=AQIsuqmY2u2w9gAAAWL_TLxTQSYEqWZVXLEzP6Q0SJFwjFRoDBUObei7YQ&app=1799625&sync=0&v=1&ut=1I2waOv-FKM8c1"
    

    The response from the above upload API is of type urn:li:digitalmediaAsset:{ID}. An example is: urn:li:digitalmediaAsset:C5522AQHn46pwH96hxQ. This can be used in adUnitV2 field.

    Test AdInMail Content

    The sendTestInMail action can be used to trigger a test message for a draft message or conversation ad.

    You need to specify the Sponsored InMail campaign, the Message Ad or Conversation Ad creative and a recipient. The recipient has to be the same as the authenticated LinkedIn member. The test message can be viewed in the LinkedIn inbox of the recipient.

    POST https://api.linkedin.com/v2/adInMailContentsV2/726086?action=sendTestInMail
    
    {
     "campaign": "urn:li:sponsoredCampaign:1234",
     "creative": "urn:li:sponsoredCreative:2222",
      "recipients": ["urn:li:person:aDeeDDskD"]
    }