> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Message to Lead
> Send a direct message to a lead by their ID
Send a LinkedIn message to a lead using their ID. The lead's LinkedIn URL is looked up automatically from the database. Supports template variables like `{{firstName}}` and `{{lastName}}`.
## Request
Your API key
The lead ID to send the message to
The LinkedIn sender account ID to use. Get available senders from the [List Senders](/api-reference/endpoint/get-senders) endpoint.
The message content to send (max 8000 characters). Supports template variables:
* `{{firstName}}` - Lead's first name
* `{{lastName}}` - Lead's last name
## Response
Whether the message was sent successfully
Unique identifier for the sent message
The LinkedIn URL of the lead
The lead ID the message was sent to
Message status: `sent`
ISO 8601 timestamp when the message was sent
```bash cURL theme={null}
curl -X POST https://api.sendpilot.ai/v1/inbox/send/lead/lead_abc123 \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"senderId": "sender_def456",
"message": "Hi {{firstName}}! Thanks for connecting. I wanted to follow up on our conversation..."
}'
```
```javascript Node.js theme={null}
const leadId = 'lead_abc123';
const response = await fetch(`https://api.sendpilot.ai/v1/inbox/send/lead/${leadId}`, {
method: 'POST',
headers: {
'X-API-Key': process.env.SENDPILOT_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
senderId: 'sender_def456',
message: 'Hi {{firstName}}! Thanks for connecting...'
})
});
const result = await response.json();
```
```python Python theme={null}
import requests
lead_id = 'lead_abc123'
response = requests.post(
f'https://api.sendpilot.ai/v1/inbox/send/lead/{lead_id}',
headers={
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'senderId': 'sender_def456',
'message': 'Hi {{firstName}}! Thanks for connecting...'
}
)
result = response.json()
```
```json 200 theme={null}
{
"success": true,
"messageId": "msg_xyz789",
"recipientLinkedinUrl": "https://www.linkedin.com/in/john-doe",
"leadId": "lead_abc123",
"status": "sent",
"timestamp": "2024-02-24T15:30:00.000Z"
}
```
```json 400 theme={null}
{
"statusCode": 400,
"error": "Bad Request",
"code": "MISSING_LINKEDIN_URL",
"message": "Lead 'lead_abc123' does not have a LinkedIn URL"
}
```
```json 404 theme={null}
{
"statusCode": 404,
"error": "Not Found",
"code": "LEAD_NOT_FOUND",
"message": "Lead with ID 'lead_abc123' not found in this workspace"
}
```
```json 429 theme={null}
{
"statusCode": 429,
"error": "Too Many Requests",
"code": "DAILY_LIMIT_EXCEEDED",
"message": "LinkedIn sender 'sender_def456' has reached its daily message limit."
}
```
The lead must be a 1st-degree connection of the sender. Attempting to message a non-connected lead will result in an error.
Use template variables like `{{firstName}}` to personalize your messages. The variables are automatically replaced with the lead's actual data.
## OpenAPI
````yaml POST /v1/inbox/send/lead/{leadId}
openapi: 3.0.0
info:
title: SendPilot External API
description: >
The SendPilot API enables you to programmatically manage LinkedIn outreach
campaigns,
add leads, update lead statuses, send messages, and receive real-time
webhook notifications.
version: 1.0.0
contact:
name: SendPilot Support
email: support@sendpilot.ai
url: https://sendpilot.ai
servers:
- url: https://api.sendpilot.ai
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Credits
description: Credits and quota management
- name: Campaigns
description: Campaign management endpoints
- name: Leads
description: Lead management endpoints
- name: Lead Database
description: Lead Database search endpoints
- name: Lead Extractor
description: Lead extraction campaign endpoints
- name: Inbox
description: Direct messaging endpoints
paths:
/v1/inbox/send/lead/{leadId}:
post:
tags:
- Inbox
summary: Send message to lead
description: >
Send a LinkedIn message to a lead using their ID. The lead's LinkedIn
URL is looked up
automatically from the database. Supports template variables like
`{{firstName}}` and `{{lastName}}`.
The lead must be a 1st-degree connection of the sender.
operationId: sendMessageToLead
parameters:
- name: leadId
in: path
required: true
description: The lead ID to send the message to
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageToLeadRequest'
responses:
'200':
description: Message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageToLeadResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
SendMessageToLeadRequest:
type: object
properties:
senderId:
type: string
description: The LinkedIn sender account ID to use
message:
type: string
description: >
The message content to send. Supports template variables:
`{{firstName}}` (lead's first name), `{{lastName}}` (lead's last
name).
maxLength: 8000
required:
- senderId
- message
SendMessageToLeadResponse:
type: object
properties:
success:
type: boolean
messageId:
type: string
recipientLinkedinUrl:
type: string
leadId:
type: string
status:
type: string
enum:
- sent
timestamp:
type: string
format: date-time
required:
- success
- messageId
- recipientLinkedinUrl
- leadId
- status
- timestamp
Error:
type: object
properties:
statusCode:
type: integer
error:
type: string
code:
type: string
message:
type: string
required:
- statusCode
- message
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key for authentication
````