ClickSend

ClickSend API integration with managed authentication. Send SMS, MMS, and voice messages, manage contacts, lists, verified email addresses, and account configuration. All write operations require explicit user approval. Sending SMS/MMS/voice delivers messages to real recipients and may incur costs — confirm the recipient, content, and send timing before executing. Email address management modifies verified sender identities on the account. Use this skill when users want to send text messages, make voice calls, manage contact lists, or track message delivery. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).

byungkyu@byungkyu

Install

openclaw skills install @byungkyu/clicksend

ClickSend

Access the ClickSend API with managed authentication. Send SMS, MMS, and voice messages, manage contacts and lists, and track message delivery.

Quick Start

bash

# Get account info
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/clicksend/v3/account')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

text

https://api.maton.ai/clicksend/{native-api-path}

Maton proxies requests to rest.clicksend.com and automatically injects your authentication.

Authentication

All requests require the Maton API key in the Authorization header:

text

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

bash

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

Manage your ClickSend connections at https://api.maton.ai.

List Connections

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=clicksend&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

bash

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'clicksend'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

json

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2026-02-10T10:04:12.418030Z",
    "last_updated_time": "2026-02-10T10:06:17.059090Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "clicksend",
    "metadata": {}
  }
}

Delete Connection

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple ClickSend connections, specify which one to use with the Maton-Connection header:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/clicksend/v3/account')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

Access is scoped to SMS, MMS, voice messages, contacts, lists, verified email addresses, and account info within the connected ClickSend account.
All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.
Messaging operations (SMS, MMS, voice) deliver to real recipients and may incur costs. Confirm the recipient, content, and timing before sending.
Email address management modifies verified sender identities on the account. Deleting a verified address may affect other services that depend on it. Confirm before modifying.

API Reference

Response Format

All ClickSend API responses follow this structure:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Description of the result",
  "data": { ... }
}

Account

Get Account

bash

GET /clicksend/v3/account

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here's your account",
  "data": {
    "user_id": 672721,
    "username": "user@example.com",
    "user_email": "user@example.com",
    "balance": "2.005718",
    "user_phone": "+18019234886",
    "user_first_name": "John",
    "user_last_name": "Doe",
    "country": "US",
    "default_country_sms": "US",
    "timezone": "America/Chicago",
    "_currency": {
      "currency_name_short": "USD",
      "currency_prefix_d": "$"
    }
  }
}

SMS

Send SMS

bash

POST /clicksend/v3/sms/send
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Hello from ClickSend!",
      "source": "api"
    }
  ]
}

Parameters:

Field	Type	Description
`to`	string	Recipient phone number (E.164 format)
`body`	string	SMS message content
`source`	string	Source identifier (e.g., "api", "sdk")
`from`	string	Sender ID (optional)
`schedule`	int	Unix timestamp for scheduled send (optional)
`custom_string`	string	Custom reference (optional)

Get SMS Price

bash

POST /clicksend/v3/sms/price
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Test message",
      "source": "api"
    }
  ]
}

SMS History

bash

GET /clicksend/v3/sms/history

Query Parameters:

Parameter	Description
`date_from`	Unix timestamp for start date
`date_to`	Unix timestamp for end date
`page`	Page number (default: 1)
`limit`	Results per page (default: 15)

Inbound SMS

bash

GET /clicksend/v3/sms/inbound

SMS Receipts (Delivery Reports)

bash

GET /clicksend/v3/sms/receipts

Cancel Scheduled SMS

bash

PUT /clicksend/v3/sms/{message_id}/cancel

Cancel All Scheduled SMS

bash

PUT /clicksend/v3/sms/cancel-all

SMS Templates

List Templates

bash

GET /clicksend/v3/sms/templates

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are your templates.",
  "data": {
    "total": 1,
    "per_page": 15,
    "current_page": 1,
    "data": [
      {
        "template_id": 632497,
        "body": "Hello {name}, this is a test message.",
        "template_name": "Test Template"
      }
    ]
  }
}

Create Template

bash

POST /clicksend/v3/sms/templates
Content-Type: application/json

{
  "template_name": "Welcome Message",
  "body": "Hello {name}, welcome to our service!"
}

Update Template

bash

PUT /clicksend/v3/sms/templates/{template_id}
Content-Type: application/json

{
  "template_name": "Updated Template",
  "body": "Updated message content"
}

Delete Template

bash

DELETE /clicksend/v3/sms/templates/{template_id}

MMS

Send MMS

bash

POST /clicksend/v3/mms/send
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Check out this image!",
      "media_file": "https://example.com/image.jpg",
      "source": "api"
    }
  ]
}

MMS History

bash

GET /clicksend/v3/mms/history

Get MMS Price

bash

POST /clicksend/v3/mms/price
Content-Type: application/json

{
  "messages": [...]
}

MMS Receipts

bash

GET /clicksend/v3/mms/receipts

Voice

Send Voice Message

bash

POST /clicksend/v3/voice/send
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Hello, this is a voice message.",
      "voice": "female",
      "lang": "en-us",
      "source": "api"
    }
  ]
}

Voice Parameters:

Field	Description
`to`	Recipient phone number
`body`	Text to be spoken
`voice`	Voice gender: `male` or `female`
`lang`	Language code (e.g., `en-us`, `en-gb`, `de-de`)
`schedule`	Unix timestamp for scheduled call
`require_input`	Require keypad input (0-1)
`machine_detection`	Detect answering machine (0-1)

Available Languages

bash

GET /clicksend/v3/voice/lang

Returns list of supported languages with codes and available genders.

Voice History

bash

GET /clicksend/v3/voice/history

Note: Requires voice access enabled on account.

Get Voice Price

bash

POST /clicksend/v3/voice/price

Cancel Voice Message

bash

PUT /clicksend/v3/voice/{message_id}/cancel

Contact Lists

List All Lists

bash

GET /clicksend/v3/lists

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are your contact lists.",
  "data": {
    "total": 2,
    "data": [
      {
        "list_id": 3555277,
        "list_name": "Opt-Out List",
        "_contacts_count": 0
      },
      {
        "list_id": 3555278,
        "list_name": "Example List",
        "_contacts_count": 10
      }
    ]
  }
}

Get List

bash

GET /clicksend/v3/lists/{list_id}

Create List

bash

POST /clicksend/v3/lists
Content-Type: application/json

{
  "list_name": "My New List"
}

Update List

bash

PUT /clicksend/v3/lists/{list_id}
Content-Type: application/json

{
  "list_name": "Updated List Name"
}

Delete List

bash

DELETE /clicksend/v3/lists/{list_id}

Remove Duplicates

bash

PUT /clicksend/v3/lists/{list_id}/remove-duplicates

Contacts

List Contacts in a List

bash

GET /clicksend/v3/lists/{list_id}/contacts

Query Parameters:

Parameter	Description
`page`	Page number
`limit`	Results per page
`updated_after`	Filter contacts updated after timestamp

Get Contact

bash

GET /clicksend/v3/lists/{list_id}/contacts/{contact_id}

Response:

json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "data": {
    "contact_id": 1581565666,
    "list_id": 3555278,
    "phone_number": "+18019234886",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "custom_1": "",
    "custom_2": "",
    "custom_3": "",
    "custom_4": "",
    "organization_name": "",
    "address_city": "",
    "address_state": "",
    "address_country": "US"
  }
}

Create Contact

bash

POST /clicksend/v3/lists/{list_id}/contacts
Content-Type: application/json

{
  "phone_number": "+15551234567",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com"
}

Contact Fields:

Field	Description
`phone_number`	Phone number (E.164 format)
`first_name`	First name
`last_name`	Last name
`email`	Email address
`fax_number`	Fax number
`organization_name`	Company name
`custom_1` - `custom_4`	Custom fields
`address_line_1`, `address_line_2`	Address
`address_city`, `address_state`, `address_postal_code`, `address_country`	Address components

Update Contact

bash

PUT /clicksend/v3/lists/{list_id}/contacts/{contact_id}
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Smith"
}

Delete Contact

bash

DELETE /clicksend/v3/lists/{list_id}/contacts/{contact_id}

Copy Contact to Another List

bash

PUT /clicksend/v3/lists/{from_list_id}/contacts/{contact_id}/copy/{to_list_id}

Transfer Contact to Another List

bash

PUT /clicksend/v3/lists/{from_list_id}/contacts/{contact_id}/transfer/{to_list_id}

Email Addresses

Account configuration. These endpoints manage verified sender email addresses on the ClickSend account. Adding or deleting addresses affects which sender identities are available for email campaigns. Confirm the address and intent with the user before modifying.

List Verified Email Addresses

bash

GET /clicksend/v3/email/addresses

Add Email Address

bash

POST /clicksend/v3/email/addresses
Content-Type: application/json

{
  "email_address": "sender@example.com"
}

Delete Email Address

bash

DELETE /clicksend/v3/email/addresses/{email_address_id}

Utility Endpoints

List Countries

bash

GET /clicksend/v3/countries

Returns list of all supported countries with codes.

Pagination

ClickSend uses page-based pagination:

bash

GET /clicksend/v3/lists?page=2&limit=50

Response includes:

json

{
  "data": {
    "total": 100,
    "per_page": 50,
    "current_page": 2,
    "last_page": 2,
    "next_page_url": null,
    "prev_page_url": "...?page=1",
    "from": 51,
    "to": 100,
    "data": [...]
  }
}

Parameters:

page - Page number (default: 1)
limit - Results per page (default: 15)

Code Examples

JavaScript

javascript

const response = await fetch(
  'https://api.maton.ai/clicksend/v3/sms/send',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [
        {
          to: '+15551234567',
          body: 'Hello from ClickSend!',
          source: 'api'
        }
      ]
    })
  }
);
const data = await response.json();
console.log(data);

Python

python

import os
import requests

response = requests.post(
    'https://api.maton.ai/clicksend/v3/sms/send',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [
            {
                'to': '+15551234567',
                'body': 'Hello from ClickSend!',
                'source': 'api'
            }
        ]
    }
)
data = response.json()
print(f"Status: {data['response_code']}")

Notes

Phone numbers must be in E.164 format (e.g., +15551234567)
All timestamps are Unix timestamps (seconds since epoch)
Use source field to identify your application in analytics
Templates support placeholders like {name}, {custom_1}, etc.
SMS messages over 160 characters are split into multiple segments
Voice access requires account-level permissions
IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Status	Meaning
200	Success
400	Bad request
401	Unauthorized - invalid credentials
403	Forbidden - insufficient permissions
404	Resource not found
429	Rate limited
500	Internal server error

Response codes:

SUCCESS - Operation completed successfully
FORBIDDEN - Access denied to resource
BAD_REQUEST - Invalid request parameters
INVALID_RECIPIENT - Invalid phone number

Troubleshooting: API Key Issues

Check that the MATON_API_KEY environment variable is set:

bash

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

Ensure your URL path starts with clicksend. For example:

Correct: https://api.maton.ai/clicksend/v3/account
Incorrect: https://api.maton.ai/v3/account

ClickSend

Install

ClickSend

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

Security & Permissions

API Reference

Response Format

Account

Get Account

SMS

Send SMS

Get SMS Price

SMS History

Inbound SMS

SMS Receipts (Delivery Reports)

Cancel Scheduled SMS

Cancel All Scheduled SMS

SMS Templates

List Templates

Create Template

Update Template

Delete Template

MMS

Send MMS

MMS History

Get MMS Price

MMS Receipts

Voice

Send Voice Message

Available Languages

Voice History

Get Voice Price

Cancel Voice Message

Contact Lists

List All Lists

Get List

Create List

Update List

Delete List

Remove Duplicates

Contacts

List Contacts in a List

Get Contact

Create Contact

Update Contact

Delete Contact

Copy Contact to Another List

Transfer Contact to Another List

Email Addresses

List Verified Email Addresses

Add Email Address

Delete Email Address

Utility Endpoints

List Countries

Pagination

Code Examples

JavaScript

Python

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: Invalid App Name

Resources

Related skills