Ad InMail Contents (Legacy)

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to 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.

Warning

AdInMailContents API is available only in versions 202307 and lower

InMailContents API replaces AdInMailContents API and is available in versions 202305 and above.

You can set up the message Ad InMail 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 Advertising account 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 legal terms and custom conditions as specified by the advertiser.
    editable boolean, default="true" Flag that specifies if adInMailContent is editable.
    id long InMail content ID
    name string Content canonical name for convenience as specified by the advertiser.
    sender AdInMailSender Advertiser specified content information used to render the sender in the detail and list views. Also used for various security checks.
    subContent AdInMailStandardSubContent (deprecated), AdInMailFormSubContent (deprecated), or AdInMailGuidedRepliesSubContent Subcontent based on an advertiser's objective.
    subject string Content text subject displayed in both the list and detail view of the inbox as specified by the advertiser.
    changeAuditStamps read-only changeAuditStamps Audit changed stamps includes created and last updated timestamp.

    AdInMailStandardSubContent or AdInMailFormSubContent (Deprecated)

    Warning

    Deprecation Notice
    AdInMailStandardSubContent and AdInMailFormSubContent are deprecated as they are applicable only for Message Ads that are being discontinued. For more information on Message Ad sunset, refer to this help article help article. Alternatively, you can replace an existing Message Ad campaign with a Conversation Ad campaign as detailed in this guide. If you have questions, submit a request on the LinkedIn Developer Support Portal.

    Field Type Description
    action URL Landing page URL featuring call-to-action button which redirects to the advertiser specified URL:
  • AdInMailStandardSubContent - redirects to the landing page URL
  • AdInMailFormSubContent - redirects to the LGF
    		•
    actionText string Call-to-action advertiser specified button text
    adUnitV2 Optional DigitalMediaAssetUrn Upload Media Asset Advertiser specified message ad displayed on the right-rail ad space. For example, urn:li:digitalmediaAsset:kjdhsdf.

    AdInMailStandardSubContent or AdInMailFormSubContent

    AdInMailGuidedRepliesSubContent

    Field Type Description
    sponsoredConversation com.linkedin.common.SponsoredConversationUrn SponsoredConversation URN. Conversation contains contents of all the messages.
    rightRailAdPicture com.linkedin.common.DigitalmediaAssetUrn Advertiser specified picture displayed on the right-rail ad space within the detail view.

    AdInMailSender

    Field Type Description
    displayName Optional string Advertiser specified customized sender display name. If specified, overrides the from entity name during rendering.
    from Optional URN The advertiser specified person or organization URN sender entity identifier in the from field. If an alternate image and name are not specified, the current URN profile information is used. For example, urn:li:person:K1RwyVsdfsdNukt.
    senderType.AdInMailSenderType string The sender's type can be one of the following: "MEMBER", "COMPANY", "CUSTOM_MEMBER", "CUSTOM_COMPANY". The default is"MEMBER".
    displayPictureV2 optional DigitalmediaAssetUrn The advertiser specified display picture to be shown on the message. If specified, it overrides the from entity's picture during rendering. 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, the "sender.from" parameter is 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, the "sender.from" parameter is 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.

    Refer to Senders for Message and Conversation Ads for more details.

    Upload Message Ads Asset

    To use an asset for a Message Ad register the upload. The register upload call returns a URL to which you can then 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 a 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 the 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 recipient's LinkedIn inbox.

    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"]
}