REST API

Project Blue API

Send iMessages and SMS directly from your application. Integrate messaging into your CRM, workflows, or custom tools with a single API call.

Authentication

All API requests require a Bearer token in the Authorization header. You can generate API keys from within your Project Blue dashboard under Settings → API Keys.

Authorization: Bearer YOUR_API_KEY

Send Message

Send a message to a phone number via iMessage or SMS. If the recipient has iMessage, the message is delivered as an iMessage (blue bubble). Otherwise, it falls back to SMS automatically.

Request Body

The phone parameter is flexible — we accept formats like (555) 123-4567, 555.123.4567, +15551234567, and more. All numbers are normalized to E.164 format before sending.

When lineId is provided, we route through that line. If it is omitted, message sends continue to use default load balancing across your available lines.

Example Request

curl -X POST https://api.tryprojectblue.com/send-api-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hey! Just following up on our conversation.",
    "phone": "+15551234567"
  }'

Example with Media Attachment

curl -X POST https://api.tryprojectblue.com/send-api-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Check out this property!",
    "phone": "+15551234567",
    "mediaAttachmentUrl": "https://example.com/property-photo.jpg"
  }'

Example with AI Voice Memo

curl -X POST https://api.tryprojectblue.com/send-api-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hey, wanted to quickly touch base about your appointment tomorrow.",
    "phone": "+15551234567",
    "enableAiVoiceMemo": true
  }'

Example with Line Override

curl -X POST https://api.tryprojectblue.com/send-api-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi from a specific line.",
    "phone": "+15551234567",
    "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5"
  }'

Success Response

{
  "success": true,
  "message": "Message added to queue",
  "messageType": "iMessage",
  "phone": "+15551234567",
  "devicePhoneNumber": "+15559876543",
  "mediaAttachmentUrl": null,
  "audioAttachmentUrl": null
}

Error Response (Invalid Line Override)

{
  "error": "Invalid lineId. Expected a UUID v4 token returned from GET /get-lines."
}

CRM Integration

The Send Message endpoint works hand-in-hand with your CRM. If you have HighLevel or HubSpot connected, outbound messages sent through the API will automatically appear inside your CRM — just like messages sent from the Project Blue app.

Auto-Create Contacts

By default, shouldAutoCreateContact is true. This means if you send an outbound message and the recipient does not already exist as a contact in your CRM, we will automatically create the contact for you along with the message.

Set shouldAutoCreateContact to false if you only want messages logged for contacts that already exist in your CRM.

HighLevel

Outbound messages are synced directly into Conversations. If the contact doesn't exist and auto-create is enabled, we create the contact and the message appears in their conversation thread.

HubSpot

Outbound messages are logged as an activity on the contact record. If you have a HubSpot Inbox enabled, the message is also delivered there for your team to see and reply from.

If the contact doesn't exist and auto-create is enabled, we create the contact in HubSpot first, then log the activity.

curl -X POST https://api.tryprojectblue.com/send-api-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hey! Following up on our call earlier.",
    "phone": "+15551234567",
    "shouldAutoCreateContact": false
  }'

In the example above, the message will only be logged in your CRM if the contact already exists. No new contact will be created.

Check iMessage Availability

Check whether a phone number is reachable via iMessage before sending. Useful for routing logic or pre-qualifying contacts.

Request Body

Example Request

curl -X POST https://api.tryprojectblue.com/api-check-imessage-availability \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567"
  }'

Success Response

{
  "normalizedPhone": "+15551234567",
  "isIMessageAvailable": true
}

Error Responses

{
  "error": "Invalid phone number format (Not a valid phone number). Please use format +12345678901"
}

Get Lines

Fetch all sending lines available to your account. Pass the returned lineId value to /send-api-message when you want to force a specific line.

Example Request

curl -X GET https://api.tryprojectblue.com/get-lines \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

[
  {
    "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
    "devicePhoneNumber": "+15559876543",
    "customName": "Main Line"
  },
  {
    "lineId": "9c2e4a1b-d3f8-4e1c-a2b4-c5d6e7f8a9b0",
    "devicePhoneNumber": "+15557654321",
    "customName": "Secondary Line"
  }
]

Error Response

{
  "error": "Missing or invalid Authorization header"
}

Supported Media Types

Use the mediaAttachmentUrl field to send rich media with your messages. The following formats are supported:

Images

Videos

Contact Cards

Voice Memos & Audio

Use audioAttachmentUrl to send audio files as voice memos. The following formats are supported:

Calling

Voice calling is not provided by the Project Blue API. Outbound and inbound calls are handled by Twilio. We give you a Twilio API key in the webapp so you can build calling yourself.

Your Twilio API key is already created for you. You don't add phone numbers or caller ID — our team provides those.

Getting your Twilio API key

You must be on an API or Zapier based account.

In the Project Blue portal, go to Settings → API Keys. Your Twilio API key is exposed there.

Use Twilio's Voice API documentation to implement outbound and inbound calls.

Webhooks

Webhooks let you receive real-time notifications when messages are sent or received. Configure webhooks from within the Project Blue dashboard alongside your API keys.

Configuration

In the Project Blue app, you can:

• Paste the webhook URL you want to receive events at

• Toggle whether the webhook fires for outbound messages, inbound messages, or both

• Send test payloads to verify your endpoint is working

Webhook Payload

Every webhook event delivers the same payload structure. The direction field indicates whether the message was inbound or outbound.

Example — Inbound

{
  "message": "Yes, I'm interested! When can we schedule?",
  "destination": "+15551234567",
  "receivedAt": "2026-03-04T18:30:00.000Z",
  "direction": "inbound",
  "messageId": 456,
  "guid": "sample-guid-1234",
  "linePhoneNumber": "+15559876543"
}

Example — Outbound

{
  "message": "Great! Let's book you in for Thursday at 2pm.",
  "destination": "+15551234567",
  "receivedAt": "2026-03-04T18:31:00.000Z",
  "direction": "outbound",
  "messageId": 789,
  "guid": "sample-guid-5678",
  "linePhoneNumber": "+15559876543"
}

Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with an error field describing what went wrong.

{
  "error": "Missing or invalid Authorization header"
}