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

# 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

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:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

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

Connection Management

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

List Connections

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

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

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:

{
  "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

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:

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

API Reference

Response Format

All ClickSend API responses follow this structure:

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

Account

Get Account

GET /clicksend/v3/account

Response:

{
  "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

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

POST /clicksend/v3/sms/price
Content-Type: application/json
{
  "messages": [
    {
      "to": "+15551234567",
      "body": "Test message",
      "source": "api"
    }
  ]
}

SMS History

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

GET /clicksend/v3/sms/inbound

SMS Receipts (Delivery Reports)

GET /clicksend/v3/sms/receipts

Cancel Scheduled SMS

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

Cancel All Scheduled SMS

PUT /clicksend/v3/sms/cancel-all

SMS Templates

List Templates

GET /clicksend/v3/sms/templates

Response:

{
  "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

POST /clicksend/v3/sms/templates
Content-Type: application/json
{
  "template_name": "Welcome Message",
  "body": "Hello {name}, welcome to our service!"
}

Update Template

PUT /clicksend/v3/sms/templates/{template_id}
Content-Type: application/json
{
  "template_name": "Updated Template",
  "body": "Updated message content"
}

Delete Template

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

MMS

Send MMS

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

GET /clicksend/v3/mms/history

Get MMS Price

POST /clicksend/v3/mms/price
Content-Type: application/json
{
  "messages": [...]
}

MMS Receipts

GET /clicksend/v3/mms/receipts

Voice

Send Voice Message

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

GET /clicksend/v3/voice/lang

Returns list of supported languages with codes and available genders.

Voice History

GET /clicksend/v3/voice/history

Note: Requires voice access enabled on account.

Get Voice Price

POST /clicksend/v3/voice/price

Cancel Voice Message

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

Contact Lists

List All Lists

GET /clicksend/v3/lists

Response:

{
  "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

GET /clicksend/v3/lists/{list_id}

Create List

POST /clicksend/v3/lists
Content-Type: application/json
{
  "list_name": "My New List"
}

Update List

PUT /clicksend/v3/lists/{list_id}
Content-Type: application/json
{
  "list_name": "Updated List Name"
}

Delete List

DELETE /clicksend/v3/lists/{list_id}

Remove Duplicates

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

Contacts

List Contacts in a List

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

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

Response:

{
  "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

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

PUT /clicksend/v3/lists/{list_id}/contacts/{contact_id}
Content-Type: application/json
{
  "first_name": "Jane",
  "last_name": "Smith"
}

Delete Contact

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

Copy Contact to Another List

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

Transfer Contact to Another List

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

Email Addresses

List Verified Email Addresses

GET /clicksend/v3/email/addresses

Add Email Address

POST /clicksend/v3/email/addresses
Content-Type: application/json
{
  "email_address": "sender@example.com"
}

Delete Email Address

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

Utility Endpoints

List Countries

GET /clicksend/v3/countries

Returns list of all supported countries with codes.

Pagination

ClickSend uses page-based pagination:

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

Response includes:

{
  "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:

Code Examples

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

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

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:

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

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

1. Ensure your URL path starts with clicksend. For example:

Resources

# 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