smsmode MCP by usefulapi

The credit balance of the connected smsmode account (and sub-organisations an administrator key can see): amount and currency (negative = owed on a POST_PAY account), payment type (PRE_PAY / POST_PAY), state, monthly consumption and its limit. Good first call; check it before sending SMS. GET /commons/v1/organisations.

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

Full details of one organisation: contacts, addresses, company information, balance, monthly limit and consumption. GET /commons/v1/organisations/{id}.

{
  "type": "object",
  "properties": {
    "organisation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Organisation id (from smsmode_get_balance)."
    }
  },
  "required": [
    "organisation_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List messaging channels (SMS or RCS; flow TRANSACTIONAL / MARKETING / OTP) with default sender, daily and monthly limits and consumption. A channel id is needed to scope messages or consumption to one channel. GET /commons/v1/channels.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Channel name filter.",
      "type": "string",
      "minLength": 1,
      "maxLength": 15
    },
    "type": {
      "description": "Channel type.",
      "type": "string",
      "enum": [
        "SMS",
        "RCS"
      ]
    },
    "flow": {
      "description": "Channel flow.",
      "type": "string",
      "enum": [
        "MARKETING",
        "TRANSACTIONAL",
        "OTP"
      ]
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "page_size": {
      "description": "Results per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Details of one channel: type, flow, default sender ID and authorized sender IDs, limits and consumption. GET /commons/v1/channels/{id}.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Channel id (from smsmode_list_channels)."
    }
  },
  "required": [
    "channel_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Sent-message counts and money spent per month or per day (price amount and currency), optionally for one channel. Default: monthly, the last 3 months. GET /commons/v1/consumptions.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Only this channel (from smsmode_list_channels)."
    },
    "period_type": {
      "description": "MONTH (default) or DAY.",
      "type": "string",
      "enum": [
        "MONTH",
        "DAY"
      ]
    },
    "start_date": {
      "description": "First day, yyyy-mm-dd (default 3 months ago).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "description": "Last day, yyyy-mm-dd (default today).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "channel_type": {
      "description": "SMS (default) or RCS.",
      "type": "string",
      "enum": [
        "SMS",
        "RCS"
      ]
    },
    "flow": {
      "description": "Only this channel flow.",
      "type": "string",
      "enum": [
        "MARKETING",
        "TRANSACTIONAL",
        "OTP"
      ]
    },
    "sort_by_start_date": {
      "description": "Order by start date.",
      "type": "string",
      "enum": [
        "ASC",
        "DESC"
      ]
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "page_size": {
      "description": "Results per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One consumption record broken down by country (mcc) or network (mccMnc) with quantity and price per sub-item, optionally with delivery statuses. GET /commons/v1/consumptions/{id}.

{
  "type": "object",
  "properties": {
    "consumption_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Consumption id (from smsmode_list_consumptions)."
    },
    "group_by": {
      "description": "mccMnc = per network (default), mcc = per country.",
      "type": "string",
      "enum": [
        "mccMnc",
        "mcc"
      ]
    },
    "detail_statuses": {
      "description": "Include delivery statuses per sub-item.",
      "type": "boolean"
    }
  },
  "required": [
    "consumption_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Country and mobile network (mcc/mnc, operator) of a phone number. Only for customers with a premium smsmode subscription and, for now, only French numbers (403 otherwise). GET /commons/v1/lookup/{msisdn}.

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

Messages with delivery status (SCHEDULED, ENROUTE, DELIVERED, UNDELIVERABLE, UNDELIVERED; status.detail names the cause), recipient, sender, text, parts and price. Default window: the last 10 days. Filter by direction (MT = sent, MO = replies received), recipient, your reference, channel or campaign. Paged: pass next_page as page. GET /sms/v1/messages.

{
  "type": "object",
  "properties": {
    "direction": {
      "description": "MT = sent messages (default), MO = incoming replies.",
      "type": "string",
      "enum": [
        "MT",
        "MO"
      ]
    },
    "to": {
      "description": "Only messages to/from this number (international digits, e.g. 33610203040).",
      "type": "string",
      "maxLength": 20
    },
    "ref_client": {
      "description": "Only messages tagged with this reference.",
      "type": "string",
      "minLength": 3,
      "maxLength": 140
    },
    "origin_message_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Only replies to this message (direction MO is set automatically)."
    },
    "channel_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Only this channel."
    },
    "campaign_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Only this campaign (from smsmode_list_campaigns)."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?)?$",
      "description": "Window start (yyyy-mm-dd or yyyy-mm-ddThh:mm:ss; default 10 days ago)"
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?)?$",
      "description": "Window end (default now)"
    },
    "sort_by_sent_date": {
      "description": "Order by sent date.",
      "type": "string",
      "enum": [
        "ASC",
        "DESC"
      ]
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "page_size": {
      "description": "Results per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One message: delivery status and detail, delivery date, recipient network, text, parts and price. GET /sms/v1/messages/{id}.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Message id (from smsmode_send_sms or smsmode_list_messages)."
    },
    "channel_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "The channel the message was sent through (optional)."
    }
  },
  "required": [
    "message_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Existing SMS campaigns (grouped sends) with status SCHEDULED / ONGOING / ENDED, quantity, price and per-status delivery counts. Read only: this server does not send campaigns. GET /sms/v1/campaigns.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Only campaigns in this state.",
      "type": "string",
      "enum": [
        "SCHEDULED",
        "ONGOING",
        "ENDED"
      ]
    },
    "ref_client": {
      "description": "Only campaigns tagged with this reference.",
      "type": "string",
      "minLength": 3,
      "maxLength": 140
    },
    "channel_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Only this channel."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?)?$",
      "description": "Window start (default 10 days ago)"
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?)?$",
      "description": "Window end (default now)"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "page_size": {
      "description": "Results per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One campaign: state, period, recipients count, text, price and delivery counts per status. Use smsmode_list_messages with campaign_id for its individual messages. GET /sms/v1/campaigns/{id}.

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Campaign id (from smsmode_list_campaigns)."
    }
  },
  "required": [
    "campaign_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, SPENDS CREDIT: sends one SMS text to 1 to 10 recipients (one message each, a batch of unit messages) and texts REAL people immediately, or at send_at. Cost: every message is charged to the account at its destination's price per SMS part (GSM7: 160 characters for 1 part, 306 for 2, 459 for 3...; UNICODE: 70, 134, 201...); the accept reply returns each message's id and status (the price may only appear later on smsmode_get_message / smsmode_list_messages; total_price is given when present). A batch can partly fail: failures lists the refused numbers, which are not charged. A message is never retried: after a timeout or error, check smsmode_list_messages (ref_client) before sending again. Max 10 recipients, no campaigns or lists. Check smsmode_get_balance first. POST /sms/v1/messages.

{
  "type": "object",
  "properties": {
    "to": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 7,
        "maxLength": 20
      },
      "description": "1-10 recipient phone numbers in international format with country code, e.g. 33610203040 or +33610203040."
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1530,
      "description": "The SMS text (max 1530 characters GSM7 / 670 UNICODE; longer texts are split in parts and each part is charged)."
    },
    "from": {
      "description": "Sender ID (max 11 characters; must be authorized for the account, else smsmode refuses). Default: the channel's sender.",
      "type": "string",
      "minLength": 1,
      "maxLength": 11
    },
    "stop": {
      "description": "Append the legal 'STOP' unsubscribe mention (required for marketing messages with a custom sender in France).",
      "type": "boolean"
    },
    "encoding": {
      "description": "GSM7 (default) or UNICODE (needed for emoji and non-Latin scripts; max 670 characters).",
      "type": "string",
      "enum": [
        "GSM7",
        "UNICODE"
      ]
    },
    "send_at": {
      "description": "Schedule: a future date and time yyyy-mm-ddThh:mm:ss (a time is required; at least a few minutes ahead; smsmode's local time). Omit to send now.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?$"
    },
    "ref_client": {
      "description": "Your reference tag (3-140 characters) to find these messages later.",
      "type": "string",
      "minLength": 3,
      "maxLength": 140
    }
  },
  "required": [
    "to",
    "text"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: cancels ONE message that is still scheduled (status SCHEDULED, sent with send_at) so it is not sent; smsmode refuses messages already sent. Cannot be undone. DELETE /sms/v1/messages/{id}.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "Id of the scheduled message (from smsmode_send_sms or smsmode_list_messages)."
    }
  },
  "required": [
    "message_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}