Skip to main content
Glama

Send message

send_message
Destructive

Send one SMS from one of your numbers. Set category "marketing" for promotions (the opt-in check applies) and scheduled_at to send later. Quiet hours apply to every message: outside 8am-9pm (narrower in some states) in the recipient's local time a marketing message is refused and anything else is held until 9am, except one-time codes and replies within 4 hours of their text. In sandbox (test keys), delivery is simulated: +15005550006 delivers, +15005550002 fails, +15005550007 is filtered as spam, +15005550013 delivers after a delay, +15005550016 has no opt-in (see /docs/sandbox).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "to": "<to>",
      "body": "<body>"
    },
    "name": "send_message"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesRecipient's number in E.164
bodyYesThe message text
fromNoOne of your numbers, or a sender pool id (pool_...): TextKit picks a pool member, the same one for each recipient every time. Optional when the account has exactly one number for the key's mode.
tagsNoOptional. Your own labels, up to 10 (letters, digits, space _ . : -; up to 32 characters each; lowercased), for example a campaign or a flow. Stored on the message, sent on its webhook events, and reported by GET /v1/deliverability?group_by=tag. Filter with GET /v1/messages?tag=.
mediaNoReserved for MMS; currently returns 400 mms_not_enabled.
consentNoOptional. How the recipient agreed to your messages. A recurring non-marketing message from a number linked to a registration needs an opt-in on file for that registration; when none is, this records it and the message is sent. Never counts for marketing (use POST /v1/consent with proof). Not with scheduled_at.
categoryNoOptional. It can make a message stricter (`marketing`), never looser: what a message is comes from the sending number's registration and its wording ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing)). A message outside its registration's use case is refused with 403 campaign_mismatch.
customer_idNoOptional. Attribute to one of your customers. Defaults to the customer the from-number is assigned to; a number assigned to another customer is rejected (400).
quiet_hoursNoOptional. What to do with a message in the recipient's quiet hours: `block` refuses it (403 quiet_hours), `defer` holds it until their next 9:00am. Omitted: the account default (a single marketing send is refused; every other message is held). One-time codes are never held.
scheduled_atNoOptional. Future ISO timestamp (or epoch ms), up to 30 days out. The message is queued and the response is a scheduled_message object instead of a message. A marketing message scheduled into the recipient's quiet hours is refused now (403 quiet_hours) or, with quiet_hours defer, moved to their next 9:00am; any other message is moved.
shorten_linksNoOptional. Rewrite every http(s) link in `body` to a short link with clicks tracked (`links` on the message, `message.link_clicked` events): on <your business>.txtkto.com once your business is verified, txtkto.com before that, or your own link domain when you have an active one (POST /link-domains). The links are checked as you wrote them; texts are counted on the shortened body. Works with scheduled_at.
idempotency_keyNoOptional. Retries are already safe: the same call with the same inputs within 10 minutes is done once and answers with the first result. Pass your own key to dedupe across a longer gap, or a new one to repeat an identical call on purpose.
status_callbackNoOptional. Also send this message's status events (message.sent, message.delivered, message.failed, message.blocked) to this https URL, signed with your callback secret (POST /v1/webhooks/callback_secret; 400 callback_secret_required until it exists). Logged and retried like a webhook endpoint, under endpoint `status_callback`. Immediate sends only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / shorten_links / description
      Previous value: -"Optional. Rewrite every http(s) link in `body` to a short link with clicks tracked (`links` on the message, `message.link_clicked` events): on <your business>.txtkto.com once your business is verified, txtkto.com before that, or your own link domain when you have an active one (POST /link-domains). The links are checked as you wrote them; segments are counted on the shortened text. Works with scheduled_at."New value: +"Optional. Rewrite every http(s) link in `body` to a short link with clicks tracked (`links` on the message, `message.link_clicked` events): on <your business>.txtkto.com once your business is verified, txtkto.com before that, or your own link domain when you have an active one (POST /link-domains). The links are checked as you wrote them; texts are counted on the shortened body. Works with scheduled_at."
  2. Changed2 schema fields changed
    • changedInput schema / properties / quiet_hours / description
      Previous value: -"Optional. What to do with a message in the recipient's quiet hours: `block` refuses it (403 quiet_hours), `defer` holds it until their next 8:00am. Omitted: the account default (a single marketing send is refused; every other message is held). One-time codes are never held."New value: +"Optional. What to do with a message in the recipient's quiet hours: `block` refuses it (403 quiet_hours), `defer` holds it until their next 9:00am. Omitted: the account default (a single marketing send is refused; every other message is held). One-time codes are never held."
    • changedInput schema / properties / scheduled_at / description
      Previous value: -"Optional. Future ISO timestamp (or epoch ms), up to 30 days out. The message is queued and the response is a scheduled_message object instead of a message. A marketing message scheduled into the recipient's quiet hours is refused now (403 quiet_hours) or, with quiet_hours defer, moved to their next 8:00am; any other message is moved."New value: +"Optional. Future ISO timestamp (or epoch ms), up to 30 days out. The message is queued and the response is a scheduled_message object instead of a message. A marketing message scheduled into the recipient's quiet hours is refused now (403 quiet_hours) or, with quiet_hours defer, moved to their next 9:00am; any other message is moved."
  3. Changed1 schema field changed
    • changedInput schema / properties / shorten_links / description
      Previous value: -"Optional. Rewrite every http(s) link in `body` to a short link with clicks tracked (`links` on the message, `message.link_clicked` events): on links.jointextkit.com, or on your own link domain when you have an active one (POST /link-domains). The links are checked as you wrote them; segments are counted on the shortened text. Works with scheduled_at."New value: +"Optional. Rewrite every http(s) link in `body` to a short link with clicks tracked (`links` on the message, `message.link_clicked` events): on <your business>.txtkto.com once your business is verified, txtkto.com before that, or your own link domain when you have an active one (POST /link-domains). The links are checked as you wrote them; segments are counted on the shortened text. Works with scheduled_at."
  4. Changed3 schema fields changed
    • addedInput schema / properties / body / description
      Added value: +"The message text"
    • addedInput schema / properties / consent / properties / source / description
      Added value: +"How the recipient agreed"
    • addedInput schema / properties / to / description
      Added value: +"Recipient's number in E.164"
  5. Changed1 schema field changed
    • changedInput schema / properties / shorten_links / description
      Previous value: -"Optional. Rewrite every http(s) link in `body` to a short link on your active link domain (POST /link-domains), with clicks tracked (`links` on the message, `message.link_clicked` events). The links are checked as you wrote them; segments are counted on the shortened text. Without an active link domain the request is refused with 400 link_domain_required: short links are never put on a shared domain. Works with scheduled_at."New value: +"Optional. Rewrite every http(s) link in `body` to a short link with clicks tracked (`links` on the message, `message.link_clicked` events): on links.jointextkit.com, or on your own link domain when you have an active one (POST /link-domains). The links are checked as you wrote them; segments are counted on the shortened text. Works with scheduled_at."
  6. First observed

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as destructive and open-world, and the description adds substantial operational context beyond them: quiet-hours refusal/defer behavior, sandbox delivery numbers, idempotency dedupe behavior, and callback behavior. This is exactly the kind of compliance-sensitive detail an agent needs before calling a send tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then layers compliance rules and sandbox behavior in a logical order. It is long but mostly earns its length; the sandbox number list is useful but contributes to the density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 13-parameter send tool with nested consent and rich schema coverage, the description supplies the critical behavioral context that structured fields do not fully capture: quiet hours, sandbox behavior, idempotency, and scheduling effects. No output schema exists, but the description tells the agent enough to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 13 parameters in detail. The description reinforces category and scheduled_at semantics, but mostly mirrors what the schema already provides rather than adding new parameter-level meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Send one SMS from one of your numbers." The scope is clearly a single-message send, which distinguishes it from batch-oriented siblings even though it does not name them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: set category to marketing for promotions, use scheduled_at to send later, and quiet hours apply to every message. It does not explicitly route agents to alternatives such as send_batch or send_verification, so it stays short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.