Diagnosing LinkedIn InMail Delivery Failures via the Messaging API

Problem and takeaway

When your application sends an InMail through LinkedIn's Messaging API and the request fails, the HTTP response contains a specific status code and error payload that tells you exactly why. By matching that information to the table below, you can apply the correct remediation without guesswork.

Recognizable symptoms and likely causes

HTTP status	Error code in body	Likely cause	Quick verification
401 Unauthorized or 403 Forbidden	(often missing or vague)	Missing, expired, or invalid OAuth 2.0 access token	Check that the Authorization: Bearer header contains a token obtained via the authorized redirect flow.
400 Bad Request	INMAIL_BLOCKED_BY_RECIPIENT	The recipient has disabled InMail reception in their settings	Ask the recipient to verify Settings → Communications → Message requests or use an alternative contact method.
429 Too Many Requests	(usually none)	Daily InMail quota exhausted	Inspect response headers for X-RateLimit-Remaining: 0 and Retry-After.
400 Bad Request	INVALID_MESSAGE_CONTENT	Message violates LinkedIn policy (e.g., prohibited keywords, length > 1900 characters)	Review the message body for disallowed terms and ensure it is under the limit.

Ordered troubleshooting checks

1. Inspect the response – capture the status code, response body, and headers.
2. If 401/403 – obtain a fresh access token using the OAuth 2.0 authorization code flow (do not reuse a token stored in client‑side code). Retry the request.
3. If 400 with INMAIL_BLOCKED_BY_RECIPIENT – inform the sender that the recipient blocks InMail; suggest email or a connection request.
4. If 429 – respect the Retry-After header (wait the indicated seconds) and verify your daily quota in the LinkedIn developer dashboard before sending more.
5. If 400 with INVALID_MESSAGE_CONTENT – shorten the message, remove any prohibited keywords (e.g., spam‑like phrases), and resend.

Fixes tied to findings

• Token issue – refresh token, store it securely (server‑side or encrypted secret manager), and update the Authorization header.
• Recipient block – cannot be overridden programmatically; use another channel or ask the recipient to adjust Settings → Communications → Message requests.
• Quota exceeded – reduce sending frequency, spread requests across days, or apply for a higher quota via LinkedIn partner support.
• Content violation – edit the message to comply with LinkedIn’s InMail policy (see the developer docs for prohibited content).

Escalation criteria

Contact LinkedIn developer support only after you have:

• Refreshed the token and still receive 401/403.
• Respected Retry-After and quota limits yet continue to get 429 responses.
• Received an undocumented error code or a 5xx server error that persists after retries.

Limitations

This guide addresses API‑level failures only. It does not cover network connectivity problems, LinkedIn UI‑level blocks (e.g., recipient has blocked the sender), or issues arising from incorrect endpoint URLs.

Practical verification

After applying a fix, send a test InMail to a known‑good recipient (e.g., a test account you control). A successful request returns HTTP 200 OK with a JSON body containing the message urn. If you see 200, the issue is resolved.

Example request (replace placeholders)

curl -X POST \
  https://api.linkedin.com/v2/messaging/conversations \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "body": "Hello, this is a test InMail.",
      "content": {
        "entity": "urn:li:messageContent:plain"
      }
    },
    "recipients": ["urn:li:person:"],
    "subject": "Test"
  }'