Ad InMail Contents (Legacy)
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.
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: |
| 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: |
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: |
| 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
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
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 %FIRSTNAME%,</p><p>You can format the text as follows-</p><p><em>Italicized </em><strong>Bold </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 = <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> </p><p>Cheers, </p><p>Linkedin Team</p><p> </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.