> ## Documentation Index > Fetch the complete documentation index at: https://docs.gtm-api.com/llms.txt > Use this file to discover all available pages before exploring further. # Send LinkedIn message > Send one outbound regular LinkedIn DM on the basic messenger (outward action). Reply to an existing thread via linkedin_conversation_sid, or open a new thread to a 1st-degree connection via ln_id / sn_id or by public_identifier (slug or linkedin.com/in/ URL, resolved server-side). Guards run first: send_messages daily cap, 8000-char body cap, connection guard, attachment https:// reachability, basic-messenger surface guard. Fire-on-success: a row is inserted only on terminal success. Sends once per client_reference and place (the thread, else the person): a repeat is answered, never sent twice; on a 409 read error.context.send_outcome, never resend under a new key. When NOT: InMail to a non-connection → send_linkedin_inmail; voice note → send_linkedin_voice_message; Sales Navigator thread → send_linkedin_sales_nav_message; the connection-request note lives on linkedin-connection-requests. Bulk send: loop client-side and respect the daily cap. Contract: - MCP tool `send_linkedin_message`, registry package `mcp.linkedin/linkedin_messages`, mount `linkedin.messaging`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API; step eligible: gtm.service.orchestration can run this verb as a mass-action plan step, once per item; paced: a call spends the `send_messages` smart-limit bucket of the account it runs on, and calls of one bucket are spaced per account. A short wait is slept by the server; a longer one answers 429 `rate_limited` with `context.retry_after`, and the same call succeeds from that moment. Parallel calls on one account queue behind each other. ## OpenAPI ````yaml /api-reference/linkedin/openapi.yaml post /api/linkedin-messages/send openapi: 3.0.3 info: title: 'GTM API public contract: gtm.service.linkedin' description: >- Connected LinkedIn accounts and everything driven through them: account health and smart limits, conversations and messages, the connection graph, outbound posting, scraping, profile and company enrichment, and the antidetect browsers that execute it all. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gtm.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gtm.service.linkedin`, 189 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GTM API url: https://gtm-api.com email: support@gtm-api.com license: name: Proprietary url: https://gtm-api.com/license servers: - url: https://app.gtm-api.com/linkedin/v4 description: Production, through the app.gtm-api.com gateway security: - BearerJwt: [] TeamSid: [] tags: - name: antidetect_browser_logs description: >- Registry package `mcp.linkedin/antidetect_browser_logs`, served on MCP mount `linkedin.browsers`. - name: antidetect_browser_proxies description: >- Registry package `mcp.linkedin/antidetect_browser_proxies`, served on MCP mount `linkedin.browsers`. - name: antidetect_browsers description: >- Registry package `mcp.linkedin/antidetect_browsers`, served on MCP mount `linkedin.browsers`. - name: cloud_browser_sessions description: >- Registry package `mcp.linkedin/cloud_browser_sessions`, served on MCP mount `linkedin.browsers`. - name: cloud_browsers description: >- Registry package `mcp.linkedin/cloud_browsers`, served on MCP mount `linkedin.browsers`. - name: data_requests description: >- Registry package `mcp.linkedin/data_requests`, served on MCP mount `linkedin.data`. - name: linkedin_account_activity_log description: >- Registry package `mcp.linkedin/linkedin_account_activity_log`, served on MCP mount `linkedin.account-monitor`. - name: linkedin_account_block_log description: >- Registry package `mcp.linkedin/linkedin_account_block_log`, served on MCP mount `linkedin.account-monitor`. - name: linkedin_account_quota_hits description: >- Registry package `mcp.linkedin/linkedin_account_quota_hits`, served on MCP mount `linkedin.account-monitor`. - name: linkedin_account_smart_limits description: >- Registry package `mcp.linkedin/linkedin_account_smart_limits`, served on MCP mount `linkedin.accounts`. - name: linkedin_account_snapshots description: >- Registry package `mcp.linkedin/linkedin_account_snapshots`, served on MCP mount `linkedin.account-monitor`. - name: linkedin_account_sync_runs description: >- Registry package `mcp.linkedin/linkedin_account_sync_runs`, served on MCP mount `linkedin.account-monitor`. - name: linkedin_accounts description: >- Registry package `mcp.linkedin/linkedin_accounts`, served on MCP mount `linkedin.accounts`. - name: linkedin_auto_scrape_results description: >- Registry package `mcp.linkedin/linkedin_auto_scrape_results`, served on MCP mount `linkedin.auto-scrapes`. - name: linkedin_auto_scrape_runs description: >- Registry package `mcp.linkedin/linkedin_auto_scrape_runs`, served on MCP mount `linkedin.auto-scrapes`. - name: linkedin_auto_scrapes description: >- Registry package `mcp.linkedin/linkedin_auto_scrapes`, served on MCP mount `linkedin.auto-scrapes`. - name: linkedin_benchmarks description: >- Registry package `mcp.linkedin/linkedin_benchmarks`, served on MCP mount `linkedin.account-monitor`. - name: linkedin_connection_invitations description: >- Registry package `mcp.linkedin/linkedin_connection_invitations`, served on MCP mount `linkedin.network`. - name: linkedin_connection_requests description: >- Registry package `mcp.linkedin/linkedin_connection_requests`, served on MCP mount `linkedin.network`. - name: linkedin_connections description: >- Registry package `mcp.linkedin/linkedin_connections`, served on MCP mount `linkedin.network`. - name: linkedin_conversations description: >- Registry package `mcp.linkedin/linkedin_conversations`, served on MCP mount `linkedin.messaging`. - name: linkedin_custom_requests description: >- Registry package `mcp.linkedin/linkedin_custom_requests`, served on MCP mount `linkedin.platform`. - name: linkedin_enrichment description: >- Registry package `mcp.linkedin/linkedin_enrichment`, served on MCP mount `linkedin.enrichment`. - name: linkedin_followers description: >- Registry package `mcp.linkedin/linkedin_followers`, served on MCP mount `linkedin.network`. - name: linkedin_messages description: >- Registry package `mcp.linkedin/linkedin_messages`, served on MCP mount `linkedin.messaging`. - name: linkedin_posting description: >- Registry package `mcp.linkedin/linkedin_posting`, served on MCP mount `linkedin.content`. - name: linkedin_scraping description: >- Registry package `mcp.linkedin/linkedin_scraping`, served on MCP mount `linkedin.scraping`. paths: /api/linkedin-messages/send: post: tags: - linkedin_messages summary: Send LinkedIn message description: >- Send one outbound regular LinkedIn DM on the basic messenger (outward action). Reply to an existing thread via linkedin_conversation_sid, or open a new thread to a 1st-degree connection via ln_id / sn_id or by public_identifier (slug or linkedin.com/in/ URL, resolved server-side). Guards run first: send_messages daily cap, 8000-char body cap, connection guard, attachment https:// reachability, basic-messenger surface guard. Fire-on-success: a row is inserted only on terminal success. Sends once per client_reference and place (the thread, else the person): a repeat is answered, never sent twice; on a 409 read error.context.send_outcome, never resend under a new key. When NOT: InMail to a non-connection → send_linkedin_inmail; voice note → send_linkedin_voice_message; Sales Navigator thread → send_linkedin_sales_nav_message; the connection-request note lives on linkedin-connection-requests. Bulk send: loop client-side and respect the daily cap. Contract: - MCP tool `send_linkedin_message`, registry package `mcp.linkedin/linkedin_messages`, mount `linkedin.messaging`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API; step eligible: gtm.service.orchestration can run this verb as a mass-action plan step, once per item; paced: a call spends the `send_messages` smart-limit bucket of the account it runs on, and calls of one bucket are spaced per account. A short wait is slept by the server; a longer one answers 429 `rate_limited` with `context.retry_after`, and the same call succeeds from that moment. Parallel calls on one account queue behind each other. operationId: send_linkedin_message requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendLinkedinMessageRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/SendLinkedinMessageResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: SendLinkedinMessageRequest: type: object description: Request body of `send_linkedin_message`. properties: linkedin_account_sid: type: string minLength: 18 maxLength: 18 pattern: ^ln_ac_ description: LinkedIn account sid (ln_ac_…). linkedin_conversation_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^ln_cv_ description: >- Existing basic-messenger thread; provide this OR a profile URN. Our sid only: a raw LinkedIn 2-…== thread id is NOT accepted here, resolve it first with search_linkedin_conversations filter.conversation_hash.eq. ln_id: type: string nullable: true maxLength: 128 description: Regular-profile URN (ACoAA…) for a new thread. sn_id: type: string nullable: true maxLength: 64 description: Sales Navigator URN (ACwAA…); interchangeable with ln_id. public_identifier: type: string nullable: true maxLength: 2048 description: >- For a new thread when all you have is the person's vanity slug or linkedin.com/in/ URL: resolved server-side to the URN (own rows, then the corpus, then a lite-profile read on the sender that spends enrichment). One addressing form per call: linkedin_conversation_sid, ln_id / sn_id, or public_identifier. text: type: string minLength: 1 maxLength: 8000 description: >- Message body; 1..8000 chars. Sent verbatim: the platform renders no merge fields, a {{first_name}} goes out as those braces. attachments: type: array items: type: object properties: file_base64: type: string minLength: 1 description: >- The file itself: a data:;base64,<...> URL or bare base64. Exactly one of file_base64 / file_url. file_url: type: string maxLength: 2048 format: uri description: >- An https URL of the file, downloaded by the backend and encoded for you (public hosts on port 443 only, no credentials in the URL; a request_media_upload file_url works once uploaded). Exactly one of file_base64 / file_url. Refused 422 on this member before anything is dispatched: attachment_url_invalid (not https, a port other than 443, credentials), attachment_url_host_forbidden (a private or reserved address), attachment_fetch_failed, attachments_too_large. file_name: type: string minLength: 1 maxLength: 255 description: >- Display filename shown to the recipient. Derived from the URL path when omitted on the file_url arm. file_type: type: string minLength: 1 maxLength: 255 description: >- MIME type. Read off the data: prefix or the fetched Content-Type when omitted. file_byte_size: type: integer minimum: 1 description: >- Advisory only: the backend measures the real size and sends that. description: >- Exactly one of file_base64 / file_url per item. Decoded bytes across ALL attachments of one send may not exceed 35 MB, derived from the node's own 50 MB body limit and base64's 4/3 inflation; over it the send is refused with attachments_too_large before a browser dispatch is spent. description: >- Exactly one of file_base64 / file_url per item; 35 MB decoded total per send. An item whose file_type is video/* is delivered as a playable video in the thread; any other type arrives as a generic file attachment. stop_if_replied_after: type: string nullable: true format: date-time description: >- ISO 8601 UTC moment. When given, the thread is read from LinkedIn before the send and the send is refused with 409 replied if the person wrote after this moment (context.linkedin_message_sid names their message: read it before you send again); 503 reply_check_unavailable when that read fails, nothing sent, retry after retry_after. Omit or null to send regardless. client_reference: type: string nullable: true maxLength: 255 description: >- Your key for this ONE message (max 255, byte for byte): one key per message, the same key on every repeat of it. The key and its place (the thread, else the person) are one message whatever it says, and a repeat never goes out twice: it answers 200 with the row the first send stored (result.idempotent_replay, result.content_differs when this request says something else) or 409 naming error.context.send_outcome (in_flight, unknown with retry_after and send_decisive_at, or sent; not_sent with blocking_activity_log_sid when another message holds the place). The same key at another place is another message. Without a key the same words to the same place count as a repeat for an hour after they went out. Stored on the row and searchable; check_linkedin_message_sent asks by it. confirmed_not_sent: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^ln_al_ description: >- A person's word that an earlier attempt of THIS message is not on LinkedIn: its activity_log_sid (ln_al_...), from the 409 or check_linkedin_message_sent, given only after someone looked at the conversation. Taken once the attempt can no longer land (before that: 409 send_outcome_unknown, waiting_for may_still_land, retry_after and send_decisive_at that moment): it settles that attempt not_sent and this request goes out. Moot when the attempt is no longer in doubt; another message's sid is 422 not_this_message. confirmed_sent: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^ln_al_ description: >- A person's word that an earlier attempt of THIS message IS on LinkedIn: its activity_log_sid, as for confirmed_not_sent (never both). Taken at once; it settles the attempt sent and sends nothing: the answer is 409 concurrent_send_in_flight with send_outcome sent, or 200 with the row once it is stored. Another message's sid is 422 not_this_message; an attempt already proved not sent is 409 confirmed_sent_contradicts. required: - linkedin_account_sid - text SendLinkedinMessageResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: object nullable: true properties: sid: type: string team_sid: type: string linkedin_account_sid: type: string linkedin_conversation_sid: type: string messenger_type: type: string enum: - linkedin - sales_navigator - recruiter description: >- Messenger surface: the basic LinkedIn messenger, Sales Navigator, or the LinkedIn Recruiter inbox. linkedin_type: type: string enum: - message - inmail - connection_note - system description: >- Channel sub-kind: regular DM / premium InMail / system-seeded connection note / a notice LinkedIn posted into the thread on someone's action (system: a rename, a member added or removed, a member leaving; the body is LinkedIn's own sentence, the sender the acting member; not a message: it takes no reaction and no recall, draw it as history). type: type: string enum: - inbox - outbox description: 'Direction relative to our account: received / sent.' automation: type: string enum: - auto - manual - synced description: >- Writer provenance: a sequence runner (auto), a person through a send tool (manual), or the messages sync (synced). An invitation note is a synced row labelled linkedin_type=connection_note; the 'connect' value left on 2026-09-20 with the seeders that were its only writer and never shipped. ln_member_id: type: string nullable: true description: >- The counterpart's member id, decoded from whichever LinkedIn id the thread carries. Null only on a thread with an organization (a Message Ads page names nobody). ln_id: type: string nullable: true sn_id: type: string nullable: true recruiter_id: type: string nullable: true description: >- The counterpart's LinkedIn Recruiter (talent) profile id, denormalized from the parent recruiter thread. Null off the recruiter surface. nickname: type: string nullable: true subject: type: string nullable: true text: type: string client_reference: type: string nullable: true attachments: type: array items: type: object properties: id: type: string urn: type: string description: >- digitalmediaAsset URN; the attachment_urn the download tools take. name: type: string content_type: type: string content_url: type: string file_byte_size: type: number path: type: string description: 'Outbound rows only: the https:// URL we uploaded from.' size: type: number description: Outbound rows only. reactions: type: array nullable: true items: type: object properties: emoji: type: string count: type: number is_viewer_reacted: type: boolean first_reacted_at: type: string nullable: true required: - emoji - count - is_viewer_reacted - first_reacted_at is_deleted: type: boolean message_hash: type: string sent_at: type: string custom_content: type: object nullable: true additionalProperties: {} created_at: type: string updated_at: type: string deleted_at: type: string nullable: true required: - sid - team_sid - linkedin_account_sid - linkedin_conversation_sid - messenger_type - linkedin_type - type - automation - ln_member_id - ln_id - sn_id - recruiter_id - nickname - subject - text - client_reference - attachments - reactions - is_deleted - message_hash - sent_at - custom_content - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms pacing: type: object properties: linkedin_account_sid: type: string description: The account whose bucket the call spent. limit_type: type: string description: The smart-limit bucket the call spent, e.g. send_messages. next_call_after: type: string description: >- ISO 8601, the same form as retry_after: the moment this same call goes through again without waiting. The next pacing slot while the day has budget left, the daily reset when it has none, the end of a LinkedIn lock while one stands. remaining_today: type: integer minimum: 0 description: >- daily_limit minus done_today_count of that bucket, after this call. required: - linkedin_account_sid - limit_type - next_call_after - remaining_today required: - success - operation - action - item - result - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gtm.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.