BulkSMS MCP by usefulapi

Show the BulkSMS account: username, credit balance, credit limit, whether credit transfer is allowed, the daily message quota (size and remaining today) and the sender ids this account may use. Company and billing details are left out. BulkSMS REST: GET /profile.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List sent (SENT) and received (RECEIVED) SMS messages, newest first by default. BulkSMS limits the window to the last 7 days unless submission_date_from is given. To page newest-first, pass before_id = the smallest id of the previous page; with sort_order ASCENDING pass after_id = the largest id of the previous page. REST: GET /messages with a `filter` built from the arguments.

{
  "type": "object",
  "properties": {
    "type": {
      "description": "SENT = outgoing (MT), RECEIVED = incoming replies (MO).",
      "type": "string",
      "enum": [
        "SENT",
        "RECEIVED"
      ]
    },
    "status_type": {
      "description": "Filter by delivery status type.",
      "type": "string",
      "enum": [
        "ACCEPTED",
        "SENT",
        "DELIVERED",
        "FAILED"
      ]
    },
    "status_id": {
      "description": "Filter by full status id, e.g. FAILED.BLOCKED or FAILED.EXPIRED.",
      "type": "string",
      "pattern": "^[A-Za-z_.]{1,64}$"
    },
    "submission_id": {
      "description": "Only messages of this submission (the submission.id of a sent message).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]{1,64}$"
    },
    "submission_date_from": {
      "description": "Only messages submitted at or after this time, ISO 8601 with offset, e.g. 2026-10-01T00:00:00Z.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$"
    },
    "user_supplied_id": {
      "description": "The userSuppliedId you set when sending (SENT messages only).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]{1,20}$"
    },
    "before_id": {
      "description": "Only messages with an id lower than this (older), for paging.",
      "type": "string",
      "pattern": "^\\d{1,20}$"
    },
    "after_id": {
      "description": "Only messages with an id higher than this (newer), for paging with sort_order ASCENDING: pass the largest id of the previous page.",
      "type": "string",
      "pattern": "^\\d{1,20}$"
    },
    "sort_order": {
      "description": "Default DESCENDING (newest first).",
      "type": "string",
      "enum": [
        "ASCENDING",
        "DESCENDING"
      ]
    },
    "limit": {
      "description": "Maximum number of messages, default 50. The API may return fewer even if more exist: page with before_id.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one sent or received message by its id: body, recipient, delivery status, number of parts and credit cost. BulkSMS REST: GET /messages/{id}.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "The message id (from list_messages or send_message)."
    }
  },
  "required": [
    "message_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the received (RECEIVED) replies linked to a sent message id. Only messages sent with a REPLIABLE sender have linked replies. An empty list means none or an unknown id. BulkSMS REST: GET /messages/{id}/relatedReceivedMessages.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "The id of the SENT message."
    }
  },
  "required": [
    "message_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List phone numbers the account may not send to (added via the API, by a recipient replying STOP, or by BulkSMS). To page, pass min_id = the largest id of the previous page + 1. BulkSMS REST: GET /blocked-numbers.

{
  "type": "object",
  "properties": {
    "min_id": {
      "description": "Only records with id >= min_id (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Maximum records, default 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the account's webhooks (name, trigger SENT/RECEIVED, active flag, invoke option). Only the host of each webhook URL is shown: the path and query can hold a secret. Read-only: webhooks are not changed by this server. BulkSMS REST: GET /webhooks.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: SENDS REAL SMS to real people and SPENDS CREDITS from the user's BulkSMS account; it cannot be undone or recalled. One message text to 1 to 10 phone numbers in international format (e.g. +447700900000). Cost = credits per message part x number of parts x number of recipients (about 1 credit per 160-character GSM part to a standard-route destination; the exact cost depends on the destination and appears as creditCost on the sent messages afterwards). Messages longer than one part are concatenated up to max_parts parts (default 3). Non-GSM characters (emoji, accents outside GSM 03.38) are replaced by "?" unless auto_unicode is true, which sends Unicode (shorter parts, more credits). Messages to blocked numbers still cost credits. Only send what the user explicitly asked for, confirm the text and recipients first. No groups, no scheduling. Texts containing BulkSMS template placeholders such as {F0###}, {fn###} or {sn###} are rejected (they would merge contact data). BulkSMS REST: POST /messages.

{
  "type": "object",
  "properties": {
    "to": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "1 to 10 recipient numbers in international format with country code, e.g. +447700900000 or 27831234567."
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1600,
      "description": "The message text."
    },
    "from": {
      "description": "Optional sender id: an allowed international number or a short alphanumeric name (see get_profile originAddresses). Omit to use the account default.",
      "type": "string",
      "minLength": 1,
      "maxLength": 15
    },
    "auto_unicode": {
      "description": "If true, a text with characters outside GSM 03.38 is sent as Unicode instead of having them replaced by '?'. Default false.",
      "type": "boolean"
    },
    "max_parts": {
      "description": "Cap on concatenated parts (and so on cost per recipient). Default 3.",
      "type": "integer",
      "minimum": 1,
      "maximum": 6
    },
    "user_supplied_id": {
      "description": "Your own reference (max 20 characters) stored on the messages, usable as a filter in list_messages.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]{1,20}$"
    }
  },
  "required": [
    "to",
    "body"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: adds ONE phone number to the account's blocked list, so that no further messages are sent to it (a send to a blocked number fails with FAILED.BLOCKED and still costs credits). This API has no way to remove a block again: do it only when the user asks for it. BulkSMS REST: POST /blocked-numbers.

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "minLength": 1,
      "description": "The number in international format, e.g. +447700900000 or 447700900000."
    }
  },
  "required": [
    "phone_number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}