Sponsored InMail is a message delivered to a LinkedIn member’s InMail inbox. Sponsored InMail provides 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, Sponsored InMail is a branded message with a call-to-action button that takes the user to an advertiser's landing page.

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.

If you are using legacy permissions, please refer to this page for requesting legacy permissions.

Requirements

Before you get started, you must have a Sponsored InMail Campaign and Creative under an Ad Account.

See the following documentation if you need help:

Schema

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.
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 Union [AdInMailStandardSubContent, AdInMailLeadGenSubContent, AdInMailFormSubContent] 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 both in both the list and detail view of the inbox. 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 this URL. Specified by the advertiser.
actionText string The text on the call-to-action button. Specified by the advertiser.
adUnitV2 Optional DigitalMediaAssetUrn Upload Media Asset The ad to be displayed on the right-rail ad space with this Sponsored InMail. Specified by the advertiser. For example, urn:li:digitalmediaAsset:kjdhsdf.

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 Sponsored InMail. 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 Sponsored InMail was sent. The from field must be a person 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.

Create Sponsored InMail Content

POST https://api.linkedin.com/v2/adInMailContentsV2
{
    "account": "urn:li:sponsoredAccount:516413367",
    "body": {
        "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)",
            "adUnit": "urn:li:media:/AAEAAQAAAAAAAAmzAAAAJDhjODg1NTQ5LTMwMWUtNDdmNS05NmZmLTJmNjA4OWFiY2VmZA.png"
        }
    },
    "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 Sponsored InMail Content, only the "sender.from" parameter can be used to set a sender. Other AdInMailSender parameters are ignored.

Update Sponsored InMail Content

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.

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

Sample Request

In the following example, the name field is changed.

POST https://api.linkedin.com/v2/adInMailContentsV2/644954
{
    "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 Sponsored InMail Content, only the "sender.from" parameter can be used to set a sender. Other AdInMailSender parameters are ignored.

Get Sponsored InMail Content

GET https://api.linkedin.com/v2/adInMailContentsV2/{adInMailContentId}
{
    "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",
        "displayPicture": "urn:li:media:AAEAAQAAAAAAAAAzAAAAJDU1YTNkZDFhLTBiNmYtNDdiYS1iMzI1LTFiODA0OWQwNjVkMQ.png",
        "from": "urn:li:person:K1RwyVNukt"
    },
    "subContent": {
        "com.linkedin.ads.AdInMailStandardSubContent": {
            "action": "http://landingPageUrlOnAction.com/checkoutcart",
            "actionText": "Buy (Call to action text)",
            "adUnit": "urn:li:media:/AAEAAQAAAAAAAAmzAAAAJDhjODg1NTQ5LTMwMWUtNDdmNS05NmZmLTJmNjA4OWFiY2VmZA.png"
        }
    },
    "subject": "Subject text "
}

Batch Get

You can also fetch multiple Sponsored InMail 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><ul><li>Bullet1</li><li>Bullet2</li></ul><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><li>Point 2</li></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",
                "displayPicture": "urn:li:media:/AAEAAQAAAAAAAAl_AAAAJDExNzQ2NGRiLTEyYWUtNDBmZi1iYjcyLTZjZTczNmIyYjBiNw.png",
                "from": "urn:li:person:K1RwyVNukt"
            },
            "subContent": {
                "com.linkedin.ads.AdInMailStandardSubContent": {
                    "action": "http://api.linkedin.com",
                    "actionText": "Click here",
                    "adUnit": "urn:li:media:/AAEAAQAAAAAAAACgAAAAJGNmNjRiMmY0LTVhMjMtNDI2Ny1iMDgxLWM0MTA5MjU2ZGQ3Ng.jpg"
                }
            },
            "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",
                "displayPicture": "urn:li:media:/AAEAAQAAAAAAAACgAAAAJGNmNjRiMmY0LTVhMjMtNDI2Ny1iMDgxLWM0MTA5MjU2ZGQ3Ng.jpg",
                "from": "urn:li:person:K1RwyVNukt"
            },
            "subContent": {
                "com.linkedin.ads.AdInMailStandardSubContent": {
                    "action": "http://landingPageUrlOnAction.com/checkoutcart",
                    "actionText": "Buy (Call to action text)",
                    "adUnit": "urn:li:media:/AAEAAQAAAAAAAAmzAAAAJDhjODg1NTQ5LTMwMWUtNDdmNS05NmZmLTJmNjA4OWFiY2VmZA.png"
                }
            },
            "subject": "Subject text "
        }
    },
    "statuses": {}
}

As a LinkedIn Ad Account manager, you can manage senders for a Sponsored InMail Campaign you've created.

Note:

  • Sponsored InMail messages must be sent from LinkedIn members and not from a company.
  • You can make sender permission requests for Sponsored InMail Campaigns to your 1st degree connections.
  • Once a sender request for Sponsored InMail Campaign is sent, you can’t cancel it. However, you can remove senders. See removing and changing Sponsored InMail Senders.
  • When sender permission requests are sent, senders are granted access to the associated Sponsored InMail campaign and account. If the senders are not already a part of your account, they are added with the VIEWER role.
  • Account Managers, Campaign Managers, and Creative Managers can add Sponsored InMail senders. Users with role VIEWER cannot.

For more information, see:

Field Type Description
account SponsoredAccountUrn The account for the permission. For example, urn:li:sponsoredAccount:5869457.
member PersonUrn The member for the permission. For example, urn:li:person:K1RwyVNukt.
state State The actual permission value of the account/member pair. Possible values are:
  • REQUESTED - The assignment has been requested to be approved.
  • APPROVED - The assignment has been approved and is valid until it expires or forever if there is no expiration.
  • REVOKED - The assignment (which was once approved) has now been revoked.
  • REJECTED - A request for the assignment to be approved was rejected.

Create Sender Permissions

The following items are validated before the creation of sender permissions:

  • The requester calling this API should be a first degree connection to the requested member (recipient).
  • The requester calling this API should have write access to the Ad Account that the request is for.

Update Sender Permissions

If an existing sender permission does not exist, an UPDATE request creates one.

The following items are validated before updating sender permissions:

  • The requester must have write access to the Ad Cccount.
  • If the member is the one who has been requested the “sender permissions” (recipient), then that member can change the state to APPROVED or REJECTED.

If the member updates this endpoint to request to the sender, a response is returned with a 304 Not Modified status.

Allowed State Transitions

The requester can request access by setting the state to REQUESTED.

When a recipient is deleted from the Ad Accounts using AdAccountUsersV2, the state for that Sender Permission is changed from REQUESTED to REVOKED.

Similarly, when the recipient is given access to the Ad Account, the sender permission state changes from REVOKED to REQUESTED.

![Requester sender permissions]Requester sender permissions

The recipient can change a state from:

  • REQUESTED to APPROVED
  • REQUESTED to REJECTED
  • APPROVED to REJECTED
  • REJECTED to APPROVED

![Recipient sender permissions]Recipient sender permissions

PUT https://api.linkedin.com/v2/adInMailMemberSenderPermissions/account={encoded SponsoredAccounturn}&member={encoded person urn}
{
    "account": "{sponsoredAccount urn}",
    "member": "{person urn}",
    "state": "{state}"
}

Sample Request

PUT https://api.linkedin.com/v2/adInMailMemberSenderPermissions/account=urn%3Ali%3AsponsoredAccount%3A516986977&member=urn%3Ali%3Aperson%3A_mVMF2Kp8p
{
    "account": "{sponsoredAccount urn}",
    "member": "{person urn}",
    "state": "{state}"
}

A successful response returns a 200 OK HTTP status code.

A failed response returns a 400 Bad Request status code and one of the following error responses:

  • MISSING_READ_ACCESS - When the recipient does not have read access to the account
  • INVALID_STATE_TRANSITION - When an invalid state transition is made. For example, setting state from “APPROVED” to “REQUESTED”.
  • UNAUTHORIZED_STATE_TRANSITION - When a member who is trying to update doesn’t have permission. For example, if a requester updating state to “APPROVED” for a sender or recipient is trying to change the state for a sender permission that does not exist.

Find Sender Permissions by Account

All Sender Permissions granted for an Ad Account can be fetched using the following API. This API takes in a sponsoredAccount URN in the account parameter. Note that the member you're making this call on behalf of must have at least read access to the requested Ad Account.

GET https://api.linkedin.com/v2/adInMailMemberSenderPermissions/account={Encoded SponsoredAccount urn}?q=account

Sample Response

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:516986977",
            "member": "urn:li:person:LBSWch4wcA",
            "state": "APPROVED"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

A 400 Bad Request with reason=NO_PERMISSION_ON_ENTITY is returned if the requesting member does not have access to the requested Ad Account.

Find Sender Permissions by Member

The following API allows a member to fetch all Sender Permissions they have across multiple Ad Accounts. This API takes in a person URN in the member parameter.

GET https://api.linkedin.com/v2/adInMailMemberSenderPermissions/member={encoded person urn}?q=member
GET https://api.linkedin.com//v2/adInMailMemberSenderPermissions/member=urn%3Ali%3Aperson%3AK1RwyVNukt?q=member

Sample Response

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:516413367",
            "member": "urn:li:person:K1RwyVNukt",
            "state": "APPROVED"
        },
        {
            "account": "urn:li:sponsoredAccount:516986977",
            "member": "urn:li:person:K1RwyVNukt",
            "state": "APPROVED"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

A 400 Bad Request with reason=NO_PERMISSION_ON_ENTITY is returned if the requesting member does not have access to view another member’s sender permissions across all the accounts. This leads to an Access Permission error response due to NO_PERMISSION_ON_ENTITY.

For more details, see the following documentation:

Upload Sponsored InMail Asset

To upload an asset for Sponsored InMail, 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 Sponsored InMail, 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:company: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.