Servers Playground How we check Add a server Log in

TextKit

Working

com.jointextkit/textkitv1.0.0 Domain verified

SMS for developers: send and receive texts, verify phones, and buy US and Canada numbers.

Communication

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.jointextkit.com

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

activate_automation Destructive

Turn an automation on, so tracked events start runs. With a live number it texts real people.

idstring, required

Automation id

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

TextKit MCP server | mcptry

TextKit

Working

com.jointextkit/textkitv1.0.0 Domain verified

SMS for developers: send and receive texts, verify phones, and buy US and Canada numbers.

Communication

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.jointextkit.com

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

activate_automation Destructive

Turn an automation on, so tracked events start runs. With a live number it texts real people.

idstring, required

Automation id

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

Tools (142)

activate_automation

Turn an automation on, so tracked events start runs. With a live number it texts real people.

destructive

Argument	Type	Description
id*	string	Automation id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    }
  }
}

add_to_list

Add contacts to a list by contact_ids and/or phone_numbers (up to 1,000; numbers must already be contacts).

destructive

Argument	Type	Description
id*	string	List id
contact_ids	array
phone_numbers	array

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id"
    },
    "contact_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "phone_numbers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

assign_number_to_customer

Platforms: attribute a number (and its messages and usage) to one of your customers, or clear it with customer_id null.

destructive

Argument	Type	Description
customer_id*	string	A customer id, or null to unassign
phone_number*	string	E.164 number you own

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_number",
    "customer_id"
  ],
  "properties": {
    "customer_id": {
      "type": "string",
      "nullable": true,
      "description": "A customer id, or null to unassign"
    },
    "phone_number": {
      "type": "string",
      "description": "E.164 number you own"
    }
  }
}

bulk_purchase_numbers

Buy several numbers in one area code at once (e.g. for a sender pool). Live numbers are billed monthly each.

destructive

Argument	Type	Description
tags	array
pool_id	string	Add the new numbers to this pool
quantity*	integer
area_code*	string
idempotency_key	string	Optional. 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.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "area_code",
    "quantity"
  ],
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "pool_id": {
      "type": "string",
      "description": "Add the new numbers to this pool"
    },
    "quantity": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1
    },
    "area_code": {
      "type": "string"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional. 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."
    }
  }
}

bulk_update_contacts

Add tags to, remove tags from, or delete many contacts by id.

destructive

Argument	Type	Description
ids*	array
tags	array	Required for add_tags and remove_tags
action*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "action",
    "ids"
  ],
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 500
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      },
      "description": "Required for add_tags and remove_tags"
    },
    "action": {
      "enum": [
        "add_tags",
        "remove_tags",
        "delete"
      ],
      "type": "string"
    }
  }
}

bulk_update_numbers

Act on many numbers at once: tag, untag, assign to a customer, or release. Releasing cannot be undone.

destructive

Argument	Type	Description
ids*	array
tags	array	add_tags / remove_tags. Lowercased; up to 20 per number.
label	string	set_label; null clears
action*	string
confirm	string	release only
pool_id	string	add_to_pool / remove_from_pool

Input schema (JSON)

{
  "type": "object",
  "required": [
    "ids",
    "action"
  ],
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 1000
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "add_tags / remove_tags. Lowercased; up to 20 per number."
    },
    "label": {
      "type": "string",
      "nullable": true,
      "maxLength": 64,
      "description": "set_label; null clears"
    },
    "action": {
      "enum": [
        "add_to_pool",
        "remove_from_pool",
        "add_tags",
        "remove_tags",
        "set_label",
        "release"
      ],
      "type": "string"
    },
    "confirm": {
      "type": "string",
      "description": "release only"
    },
    "pool_id": {
      "type": "string",
      "description": "add_to_pool / remove_from_pool"
    }
  }
}

cancel_automation_run

Cancel a run in progress.

destructive

Argument	Type	Description
id*	string	Automation id
run_id*	string	Run id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "run_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    },
    "run_id": {
      "type": "string",
      "description": "Run id"
    }
  }
}

cancel_batch

Cancel a batch. Messages already sent stay sent.

destructive

Argument	Type	Description
id*	string	Batch id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    }
  }
}

cancel_scheduled_message

Cancel a scheduled message before it sends.

destructive

Argument	Type	Description
id*	string	Scheduled message id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Scheduled message id"
    }
  }
}

check_verification

Check a verification code submitted by a user, by the phone or email it went to. Returns {verified, status, channel, charged}. Billed only when verified is true.

destructive

Argument	Type	Description
code*	string	The code last sent
email	string	The address the code was emailed to. After a fallback, check by `email`: the code proves the address, not the phone, and a check by `phone` answers 409 `invalid_state`.
phone	string	The number the code was texted to. Send this or `email`.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "code"
  ],
  "properties": {
    "code": {
      "type": "string",
      "description": "The code last sent"
    },
    "email": {
      "type": "string",
      "description": "The address the code was emailed to. After a fallback, check by `email`: the code proves the address, not the phone, and a check by `phone` answers 409 `invalid_state`."
    },
    "phone": {
      "type": "string",
      "description": "The number the code was texted to. Send this or `email`."
    }
  }
}

clone_number_pool

Copy a sender pool under a new name.

destructive

Argument	Type	Description
id*	string	Pool id
name	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Pool id"
    },
    "name": {
      "type": "string"
    }
  }
}

connect_integration

Connect a tool so its people sync in as contacts, in a list of their own, every 6 hours: Mixpanel (projectId, username, secret = a service account; sourceId = cohort id), Amplitude (apiKey, secretKey, sourceId), HubSpot (accessToken), Shopify (shopDomain, accessToken), Salesforce, or a webhook. Before calling, ask which event or property shows people agreed to texts (consentEvent / consentField) and which property holds their phone (phoneField). Use credentials the person gives you or keeps in their environment; they are proved with one read, sealed, and never returned.

destructive

Argument	Type	Description
mode	string	Mixpanel / Amplitude: pull with credentials every 6 hours (default when credentials are sent), or push: no credentials, the tool's cohort sync posts to the ingest URL.
name	string	What to call it (default: the tool and its source).
apiKey	string	Amplitude API key.
region	string	Mixpanel / Amplitude data residency.
secret	string	Mixpanel service account secret.
clientId	string	Salesforce consumer key, or Shopify client id.
provider*	string

create_api_key

Create an API key for an app you are building, to store as a secret in its environment (for example TEXTKIT_API_KEY) so the app can send texts itself. Same mode (test or live) as this connection; optional scopes limit it. The secret is returned once; the account owner is emailed.

destructive

Argument	Type	Description
name*	string	What the key is for, e.g. "Booking app"
scopes	array	Limit the key to these scopes (see /docs/authentication). Omit for full access (full-access callers only).

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "What the key is for, e.g. \"Booking app\""
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Limit the key to these scopes (see /docs/authentication). Omit for full access (full-access callers only)."
    }
  }
}

create_automation

Create a triggered text flow (as a draft): when trigger.event is tracked, run steps such as send_sms, wait, wait_for_event, and condition branches. Example: on cart_abandoned, wait 3600s, then if checkout_completed was not received send a reminder. Drafts send nothing until activated.

destructive

Argument	Type	Description
from	string	One of your numbers. A sandbox number makes it a sandbox flow.
name	string
steps	array
trigger	object
topic_id	string	Skip recipients unsubscribed from this topic.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "nullable": true,
      "description": "One of your numbers. A sandbox number makes it a sandbox flow."
    },
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable handle for goto branches; assigned when omitted."
          },
          "body": {
            "type": "string",
            "maxLength": 1600,
            "description": "send_sms. Merge fields: event properties by name, {{first_name}}, {{name}}, {{phone}}, {{field:<custom>}}."
          },
          "from": {
            "type": "string",
            "description": "send_sms: overrides the flow sender."
          },
          "type": {
            "enum": [
              "send_sms",
              "wait",
              "wait_for_event",
              "condition",
              "end"
            ],
            "type": "string"
          },
          "check": {
            "type": "object",
            "description": "{kind: event_received, event} | {kind: property, property, op, value?} | {kind: contact_field, field, op, value?}. op: eq, neq, contains, gt, lt, exists, not_exists."
          },
          "event": {
            "type": "string"
          },
          "on_met": {
            "type": "string"
          },
          "seconds": {
            "type": "integer",
            "maximum": 2592000,
            "minimum": 60
          },
          "on_not_met": {
            "type": "string"
          },
          "on_timeout": {
            "type": "string"
          },
          "on_received": {
            "type": "string"
          },
          "timeout_seconds": {
            "type": "integer",
            "maximum": 2592000,
            "minimum": 60
          }
        },
        "description": "One of: send_sms {body, from?}; wait {seconds}; wait_for_event {event, timeout_seconds, on_received, on_timeout}; condition {check, on_met, on_not_met}; end. Branches are \"continue\", \"end\", or \"goto:<id of a later step>\"."
      },
      "maxItems": 20
    },
    "trigger": {
      "type": "object",
      "properties": {
        "event": {
          "type": "string"
        },
        "filters": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "op": {
                "type": "string"
              },
              "value": {},
              "property": {
                "type": "string"
              }
            }
          },
          "maxItems": 5
        }
      }
    },
    "topic_id": {
      "type": "string",
      "nullable": true,
      "description": "Skip recipients unsubscribed from this topic."
    }
  }
}

create_customer

Platforms sending for other businesses: create a customer to attribute numbers, messages and usage to.

destructive

Argument	Type	Description
name	string
metadata	object	Up to 50 string values
external_id	string	Your id for them; unique per account

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    },
    "metadata": {
      "type": "object",
      "description": "Up to 50 string values",
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "external_id": {
      "type": "string",
      "nullable": true,
      "maxLength": 200,
      "description": "Your id for them; unique per account"
    }
  }
}

create_link_domain

Add a subdomain of the user's own (links.example.com) for short links. Returns two DNS records (CNAME and TXT) the user adds at their DNS host; then verify the domain. Short links never go on a shared domain: carriers filter those.

destructive

Argument	Type	Description
domain*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "domain"
  ],
  "properties": {
    "domain": {
      "type": "string"
    }
  }
}

create_list

Create a list: a fixed group of contacts (Audience → Lists). Use a list when the user names exactly who belongs ("add these people to VIPs"); use a segment when membership follows rules.

destructive

Argument	Type	Description
name	string
description	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}

create_number_pool

Create a sender pool from numbers you own.

destructive

Argument	Type	Description
name*	string
routing	string	How a recipient gets a number. sticky: the same member every time. local: a member in the recipient's area code, else one in their time zone, else any; still the same one each time.
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 64
    },
    "routing": {
      "enum": [
        "sticky",
        "local"
      ],
      "type": "string",
      "default": "sticky",
      "description": "How a recipient gets a number. sticky: the same member every time. local: a member in the recipient's area code, else one in their time zone, else any; still the same one each time."
    },
    "description": {
      "type": "string",
      "maxLength": 280
    }
  }
}

create_schedule

Send the same text to one number every day, week or month at a local time (e.g. a weekly reminder). Every occurrence runs the usual send checks.

destructive

Argument	Type	Description
to*	string
body*	string
from	string	One of your numbers. Optional when the account has exactly one number for the key's mode.
repeat*	object
category	string	Optional. It can make each occurrence stricter (`marketing`), never looser: the sending number's registration and the wording decide ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing)).
end_date	string	Last local date it may run (inclusive).
start_date	string	First local date it may run. Defaults to today.
quiet_hours	string	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: an occurrence in quiet hours is held until the recipient's 8:00am and recorded as `deferred`.

create_segment

Save an audience (a segment, a cohort): it appears in the console under Audience → Segments, and broadcasts can be sent to it. Use this whenever the user asks to create, make or save an audience or list. Everyone who can be texted: one rule, status is subscribed. Contacts matching all (or any) of up to 10 rules. Attributes: tags, contact fields, custom fields (field = "field", key = the name), opt-in status, topic, import, created_at. Behaviour: last_message_at, last_reply_at, batch (key = batch id; value included, sent, failed, skipped or replied) and event (key = a tracked event name). Times take an ISO date or a window like 7d. It is evaluated live each time it is used, so a batch or list sent to it reaches whoever matches then.

destructive

Argument	Type	Description
name	string
match	string
rules	array
description	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "match": {
      "enum": [
        "all",
        "any"
      ],
      "type": "string",
      "default": "all"
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "field"
        ],
        "properties": {
          "op": {
            "enum": [
              "is",
              "is_not",
              "contains",
              "not_contains",
              "exists",
              "not_exists",
              "before",
              "after"
            ],
            "type": "string",
            "description": "Text fields take is / is_not / contains / not_contains / exists / not_exists; tag takes is / is_not / exists / not_exists; status, topic, import, batch and list take is / is_not; created_at takes before / after; last_message_at, last_reply_at and event take after (at or after the time), before (it happened, and the last time was before it), exists (ever) and not_exists (never). Comparisons ignore case."
          },
          "key": {
            "type": "string",
            "description": "The custom field name (field), topic id (topic), batch id (batch), or event name (event)"
          },
          "field": {
            "enum": [
              "tag",
              "first_name",
              "last_name",
              "name",
              "email",
              "company",
              "state",
              "source",
              "field",
              "import",
              "status",
              "topic",
              "created_at",
              "last_message_at",
              "last_reply_at",
              "batch",
              "event",
              "list"
            ],
            "type": "string",
            "description": "Attributes: tag, the name and profile fields, source, field (a custom field), import, status (opt-out), topic, list (in a static list), created_at. Behaviour: last_message_at (last text either way), last_reply_at (last text from them), batch (what happened to them in one batch), event (a tracked event; the newest 20,000 events are searched)."
          },
          "value": {
            "type": "string",
            "description": "status: subscribed or opted_out. topic: subscribed or unsubscribed. import: an import id. list: a list id (lst_...). batch: included, sent, failed, skipped or replied (sent, then texted the batch's number after it was created). Times (created_at, last_message_at, last_reply_at, event): an ISO date, or a window back from now such as 7d or 24h, read each time the segment is used."
          }
        }
      },
      "maxItems": 10
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}

create_template

Save a message template. Merge tags: {{first_name}}, {{name}}, {{phone}}, {{field:<custom>}}, and per-recipient variables.

destructive

Argument	Type	Description
body*	string
name*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name",
    "body"
  ],
  "properties": {
    "body": {
      "type": "string",
      "maxLength": 1600
    },
    "name": {
      "type": "string",
      "maxLength": 60
    }
  }
}

create_topic

Create a subscription topic, so people can opt out of one kind of message (e.g. promotions) and keep others.

destructive

Argument	Type	Description
name*	string
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}

create_webhook

Send events (message.received, message.delivered, message.opted_out, ...) to a URL: your app, a CRM, an automation tool. Returns the signing secret once.

destructive

Argument	Type	Description
url*	string
events	any	Event types to receive. Omit, or send "*" or [], for every event. An unknown type is a 400.
numbers	array	Optional. Only events about these of your numbers (E.164): message events by their from/to, number events by phone_number. Events about no number (batches, credits, registrations) go only to endpoints without a filter. Omit or [] for every number.
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "events": {
      "oneOf": [
        {
          "enum": [
            "*"
          ],
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Event types to receive. Omit, or send \"*\" or [], for every event. An unknown type is a 400."
    },
    "numbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Optional. Only events about these of your numbers (E.164): message events by their from/to, number events by phone_number. Events about no number (batches, credits, registrations) go only to endpoints without a filter. Omit or [] for every number."
    },
    "description": {
      "type": "string",
      "maxLength": 120
    }
  }
}

delete_automation

Delete an automation.

destructive

Argument	Type	Description
id*	string	Automation id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    }
  }
}

delete_contact

Delete a contact. Messages, consent records, and topic preferences for the number are kept.

destructive

Argument	Type	Description
id*	string	Contact id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Contact id"
    }
  }
}

delete_customer

Delete a customer.

destructive

Argument	Type	Description
id*	string	Customer id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer id"
    }
  }
}

delete_link_domain

Remove a branded link domain. Every short link already sent on it stops working.

destructive

Argument	Type	Description
id*	string	Link domain id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Link domain id"
    }
  }
}

delete_list

Delete a list (its contacts stay).

destructive

Argument	Type	Description
id*	string	List id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id"
    }
  }
}

delete_message

Delete a finished message (delivered, failed or received) and every copy of its text, for a privacy request. Opt-out records and billing are kept. Cannot be undone.

destructive

Argument	Type	Description
id*	string	Message id (msg_...)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Message id (msg_...)"
    }
  }
}

delete_number_pool

Delete a sender pool. Its numbers are kept.

destructive

Argument	Type	Description
id*	string	Pool id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Pool id"
    }
  }
}

delete_schedule

Delete a recurring schedule.

destructive

Argument	Type	Description
id*	string	Schedule id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Schedule id"
    }
  }
}

delete_segment

Delete a segment. Contacts are not touched.

destructive

Argument	Type	Description
id*	string	Segment id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Segment id"
    }
  }
}

delete_template

Delete a template.

destructive

Argument	Type	Description
id*	string	Template id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Template id"
    }
  }
}

delete_topic

Delete a topic you created (built-in topics stay).

destructive

Argument	Type	Description
id*	string	Topic id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Topic id"
    }
  }
}

delete_webhook

Delete a webhook endpoint.

destructive

Argument	Type	Description
id*	string	Webhook endpoint id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Webhook endpoint id"
    }
  }
}

disconnect_integration

Disconnect a tool: its credentials and its list are deleted; the contacts stay with their consent.

destructive

Argument	Type	Description
id*	string	Integration id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Integration id"
    }
  }
}

export_consent

The suppression list, or the full consent ledger with opt-in proof, as CSV text.

read-only

Argument	Type	Description
type	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "type": {
      "enum": [
        "suppressions",
        "ledger"
      ],
      "type": "string",
      "default": "suppressions"
    }
  }
}

export_csv

Export as CSV text for analysis: messages, deliveries, events, opt_outs, webhook_deliveries, usage, usage_monthly, audit_log or credit_history. At most 50,000 rows; narrow the date range with from and to.

read-only

Argument	Type	Description
q	string	messages: body/failure text; events: id/payload text
ok	boolean	webhook_deliveries
to	string	Inclusive; a bare date means the end of that day (UTC)
from	string	ISO date/time or epoch ms (messages, deliveries, events, webhook_deliveries)
kind*	string	messages, deliveries, events, opt_outs, webhook_deliveries, usage, usage_monthly, audit_log or credit_history
type	string	events, webhook_deliveries
actor	string	audit_log: actor id or part of the actor email
batch	string	messages, deliveries: batch id (bc_...)
action	string

export_numbers

Your numbers as CSV text.

read-only

Argument	Type	Description
q	string
tag	string
mode	string
pool	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    },
    "mode": {
      "enum": [
        "test",
        "live"
      ],
      "type": "string"
    },
    "pool": {
      "type": "string"
    }
  }
}

fallback_verification

The text did not arrive: email a new code for the same pending verification (one id, one charge). The emailed code replaces the texted one and is checked by the email address, which it proves (not the phone). Once per verification.

destructive

Argument	Type	Description
id*	string	Verification id (ver_...)
email*	string	The address to email the code to
channel	string	The channel to fall back to. Only `email` today.
user_ip	string	Optional. Your end user's IP address, counted in the same per-IP limit as POST /verify.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "email"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Verification id (ver_...)"
    },
    "email": {
      "type": "string",
      "description": "The address to email the code to"
    },
    "channel": {
      "enum": [
        "email"
      ],
      "type": "string",
      "default": "email",
      "description": "The channel to fall back to. Only `email` today."
    },
    "user_ip": {
      "type": "string",
      "description": "Optional. Your end user's IP address, counted in the same per-IP limit as POST /verify."
    }
  }
}

forget_identity

Privacy erasure: forget the phone number linked to a user_id, so its tracked events stop reaching automations.

destructive

Argument	Type	Description
user_id*	string	Your user id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "user_id"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Your user id"
    }
  }
}

get_automation

Retrieve an automation with its trigger and steps.

read-only

Argument	Type	Description
id*	string	Automation id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    }
  }
}

get_automation_run

Retrieve one run with its step-by-step timeline.

read-only

Argument	Type	Description
id*	string	Automation id
run_id*	string	Run id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "run_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    },
    "run_id": {
      "type": "string",
      "description": "Run id"
    }
  }
}

get_balance

Prepaid credit balance and auto-recharge setting.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

get_batch

Retrieve a batch with its progress counts.

read-only

Argument	Type	Description
id*	string	Batch id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    }
  }
}

get_batch_results

Results of a batch: delivered, failed, pending, replies, opt-outs (stops), spend, and failures grouped by reason.

read-only

Argument	Type	Description
id*	string	Batch id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    }
  }
}

get_consent

Whether a number is opted in or out, per registration, with its full consent history and proof.

read-only

Argument	Type	Description
phone*	string	E.164 number

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone"
  ],
  "properties": {
    "phone": {
      "type": "string",
      "description": "E.164 number"
    }
  }
}

get_contact

Retrieve a contact.

read-only

Argument	Type	Description
id*	string	Contact id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Contact id"
    }
  }
}

get_contact_topics

A contact's subscription to each topic.

read-only

Argument	Type	Description
id*	string	Contact id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Contact id"
    }
  }
}

get_customer

Retrieve a customer.

read-only

Argument	Type	Description
id*	string	Customer id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer id"
    }
  }
}

get_customer_usage

A customer's messages, verifications and spend for a period.

read-only

Argument	Type	Description
id*	string	Customer id
end	string	Default: today
start	string	Default: first day of this month

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer id"
    },
    "end": {
      "type": "string",
      "format": "date",
      "description": "Default: today"
    },
    "start": {
      "type": "string",
      "format": "date",
      "description": "Default: first day of this month"
    }
  }
}

get_deliverability

Delivery rates by day, destination carrier, or sending number.

read-only

Argument	Type	Description
end_date	string	YYYY-MM-DD
group_by	string
start_date	string	YYYY-MM-DD

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "end_date": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "group_by": {
      "enum": [
        "day",
        "carrier",
        "number"
      ],
      "type": "string"
    },
    "start_date": {
      "type": "string",
      "description": "YYYY-MM-DD"
    }
  }
}

get_integration

One connected tool and its last sync.

read-only

Argument	Type	Description
id*	string	Integration id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Integration id"
    }
  }
}

get_link_domain

One short-link domain, with the DNS records it needs.

read-only

Argument	Type	Description
id*	string	Link domain id (ld_...)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Link domain id (ld_...)"
    }
  }
}

get_list

Retrieve a list and its contact count.

read-only

Argument	Type	Description
id*	string	List id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id"
    }
  }
}

get_message

Retrieve a message by its msg_... id, with its delivery timeline.

read-only

Argument	Type	Description
id*	string	Message id (msg_...)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Message id (msg_...)"
    }
  }
}

get_number

Retrieve one of your numbers: status, sender registration, tags, pools, customer.

read-only

Argument	Type	Description
phone_number*	string	E.164 number you own

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_number"
  ],
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "E.164 number you own"
    }
  }
}

get_number_pool

Retrieve a sender pool and its numbers.

read-only

Argument	Type	Description
id*	string	Pool id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Pool id"
    }
  }
}

get_registration

A registration with its checks, status, and linked numbers.

read-only

Argument	Type	Description
id*	string	Registration id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Registration id"
    }
  }
}

get_schedule

Retrieve a recurring schedule with its recent occurrences.

read-only

Argument	Type	Description
id*	string	Schedule id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Schedule id"
    }
  }
}

get_scheduled_message

Retrieve a pending scheduled message.

read-only

Argument	Type	Description
id*	string	Scheduled message id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Scheduled message id"
    }
  }
}

get_segment

Retrieve a segment and its rules.

read-only

Argument	Type	Description
id*	string	Segment id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Segment id"
    }
  }
}

get_spend_limit

The monthly spend limit and this month's estimated spend.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

get_template

Retrieve a template.

read-only

Argument	Type	Description
id*	string	Template id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Template id"
    }
  }
}

get_toll_free_verification

A toll-free verification: status, numbers, the form, what is missing (problems), and the carriers' reason when it was rejected.

read-only

Argument	Type	Description
id*	string	Toll-free verification id (tfv_...)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Toll-free verification id (tfv_...)"
    }
  }
}

get_topic

Retrieve a topic.

read-only

Argument	Type	Description
id*	string	Topic id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Topic id"
    }
  }
}

get_usage

Usage by month, today's counters, and plan limits.

read-only

Argument	Type	Description
months	number	How many months back (default 3)

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "months": {
      "type": "number",
      "description": "How many months back (default 3)"
    }
  }
}

get_verification

Retrieve a verification by id: its status and attempts (never the code).

read-only

Argument	Type	Description
id*	string	Verification id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Verification id"
    }
  }
}

get_webhook

Retrieve a webhook endpoint.

read-only

Argument	Type	Description
id*	string	Webhook endpoint id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Webhook endpoint id"
    }
  }
}

import_contacts

Create or update up to 500 contacts per call, matched by phone_number. Attributes go in fields (up to 20 strings, e.g. plan) for segments and {{field:name}} merge tags; tags group contacts. opt_in carries consent evidence (status: false records an opt-out). import_id from the first response groups several calls; dry_run: true returns what would change and writes nothing.

destructive

Argument	Type	Description
name	string	A label for the import (first request only).
dry_run	boolean
contacts*	array
import_id	string	From a previous response, to group several requests as one import.
campaign_id	string	Applies to every opt_in row that does not name its own campaign_id
check_line_types	boolean	dry_run only. Looks up line types to count landlines; live lookups are paid, so only the first 500 numbers are checked.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "contacts"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "A label for the import (first request only)."
    },
    "dry_run": {
      "type": "boolean"
    },
    "contacts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "phone_number"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Display name. Defaults to first + last name."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 40
            },
            "maxItems": 20
          },
          "email": {
            "type": "string",
            "maxLength": 254
          },
          "notes": {
            "type": "string",
            "maxLength": 2000
          },
          "state": {
            "type": "string",
            "maxLength": 40
          },
          "fields": {
            "type": "object",
            "description": "Up to 20 string values (account id, plan, location...), usable in segments and as {{field:key}} merge fields",
            "additionalProperties": {
              "type": "string",
              "maxLength": 500
            }
          },
          "opt_in": {
            "type": "object",
            "properties": {
              "at": {
                "type": "string",
                "description": "When they opted in: ISO timestamp, date, or epoch ms"
              },
              "source": {
                "type": "string",
                "description": "web_form, keyword, paper, checkout or verbal are stored as proof; anything else is kept as a note"
              },
              "status": {
                "type": "boolean",
                "description": "true = opted in; false = unsubscribed (recorded as an opt-out)"
              },
              "page_url": {
                "type": "string",
                "format": "uri",
                "description": "The page a web-form opt-in was collected on"
              },
              "campaign_id": {
                "type": "string",
                "description": "The registration the opt-in is for. A marketing or mixed registration needs at, a recognised source, and page_url for a web form, or the row is skipped"
              }
            },
            "description": "Import only (POST /v1/contacts/import). Stored as consent evidence; never lifts an opt-out."
          },
          "source": {
            "type": "string",
            "maxLength": 60,
            "description": "Where the contact came from. Defaults to \"api\"."
          },
          "company": {
            "type": "string",
            "maxLength": 120
          },
          "last_name": {
            "type": "string",
            "maxLength": 80
          },
          "first_name": {
            "type": "string",
            "maxLength": 80
          },
          "phone_number": {
            "type": "string",
            "description": "E.164, US or Canada"
          }
        }
      },
      "maxItems": 500
    },
    "import_id": {
      "type": "string",
      "description": "From a previous response, to group several requests as one import."
    },
    "campaign_id": {
      "type": "string",
      "description": "Applies to every opt_in row that does not name its own campaign_id"
    },
    "check_line_types": {
      "type": "boolean",
      "description": "dry_run only. Looks up line types to count landlines; live lookups are paid, so only the first 500 numbers are checked."
    }
  }
}

import_opt_outs

Bring a suppression list over from another provider or tool (up to 500 numbers per call), so people who opted out there are never texted here.

destructive

Argument	Type	Description
phone_numbers*	array

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_numbers"
  ],
  "properties": {
    "phone_numbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 500
    }
  }
}

link_number_to_registration

Attach a number to an approved 10DLC registration so it can send that registration's traffic.

destructive

Argument	Type	Description
phone_number*	string	E.164 number you own
registration_id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_number",
    "registration_id"
  ],
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "E.164 number you own"
    },
    "registration_id": {
      "type": "string"
    }
  }
}

list_api_keys

List the active API keys of this mode (never the secrets).

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_audit_logs

Who changed what on the account (keys, team, webhooks, spend limit, numbers, consent, settings), newest first.

read-only

Argument	Type	Description
actor	string	Actor id (exact) or part of the actor email (case-insensitive)
limit	integer
action	string	One action, or a group prefix with a trailing dot (team., api_key.)
cursor	string
target_type	string	Target type, e.g. api_key, member, invite, webhook, number, phone
created_after	string	Entries at or after this time (ISO 8601)
created_before	string	Entries at or before this time (ISO 8601); a bare date means the end of that day (UTC)

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "actor": {
      "type": "string",
      "description": "Actor id (exact) or part of the actor email (case-insensitive)"
    },
    "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 1
    },
    "action": {
      "type": "string",
      "description": "One action, or a group prefix with a trailing dot (team., api_key.)"
    },
    "cursor": {
      "type": "string"
    },
    "target_type": {
      "type": "string",
      "description": "Target type, e.g. api_key, member, invite, webhook, number, phone"
    },
    "created_after": {
      "type": "string",
      "format": "date-time",
      "description": "Entries at or after this time (ISO 8601)"
    },
    "created_before": {
      "type": "string",
      "format": "date-time",
      "description": "Entries at or before this time (ISO 8601); a bare date means the end of that day (UTC)"
    }
  }
}

list_automation_runs

List an automation's runs, newest first.

read-only

Argument	Type	Description
id*	string	Automation id
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    }
  }
}

list_automations

List automations.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_batch_recipients

List a batch's recipients with each one's status.

read-only

Argument	Type	Description
id*	string	Batch id
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page
status	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    },
    "status": {
      "type": "string"
    }
  }
}

list_batches

List batches (broadcasts), newest first.

read-only

Argument	Type	Description
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page
status	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    },
    "status": {
      "type": "string"
    }
  }
}

list_contacts

List contacts, newest first. Filter by tag, segment_id, list_id, exact phone_number, or a free-text q (name, email, company).

read-only

Argument	Type	Description
q	string	Search text
tag	string
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page
list_id	string
segment_id	string
phone_number	string	E.164

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Search text"
    },
    "tag": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    },
    "list_id": {
      "type": "string"
    },
    "segment_id": {
      "type": "string"
    },
    "phone_number": {
      "type": "string",
      "description": "E.164"
    }
  }
}

list_customers

List your customers.

read-only

Argument	Type	Description
limit	integer
cursor	string
external_id	string	Find the customer with this external_id (0 or 1 results)

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100
    },
    "cursor": {
      "type": "string"
    },
    "external_id": {
      "type": "string",
      "description": "Find the customer with this external_id (0 or 1 results)"
    }
  }
}

list_events

List recent events (message.sent/delivered/failed/received, number.purchased/released, ...), newest first.

read-only

Argument	Type	Description
type	string
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    }
  }
}

list_integrations

The connected tools: status, settings, last sync (found, added, opted out), and their list. No credentials.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_link_domains

Your short-link domains and their status (pending_dns, dns_verified, active). A message sent with shorten_links: true needs an active one.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_list_contacts

Page through a list's contacts, most recently added first.

read-only

Argument	Type	Description
id*	string	List id
limit	integer
cursor	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id"
    },
    "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 1
    },
    "cursor": {
      "type": "string"
    }
  }
}

list_lists

List contact lists with their contact counts.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_messages

List your messages, newest first. Filter by number, direction, status, failure reason, date, batch schedule or customer.

read-only

Argument	Type	Description
to	string	Exact destination number (E.164)
tag	string	Filter to messages sent with this tag
from	string	Exact sending number (E.164)
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page
number	string	Filter to messages to or from this number
status	string
direction	string
customer_id	string	Filter to one customer's messages
schedule_id	string	Filter to the occurrences of one recurring schedule (sch_...)

list_number_pools

List sender pools.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_number_requests

Open short-code and toll-free requests.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_numbers

List the phone numbers on your account.

read-only

Argument	Type	Description
q	string	Matches digits of the number or its label
tag	string
mode	string
pool	string	Pool id
customer_id	string	Only this customer's numbers

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Matches digits of the number or its label"
    },
    "tag": {
      "type": "string"
    },
    "mode": {
      "enum": [
        "test",
        "live"
      ],
      "type": "string"
    },
    "pool": {
      "type": "string",
      "description": "Pool id"
    },
    "customer_id": {
      "type": "string",
      "description": "Only this customer's numbers"
    }
  }
}

list_opt_outs

List opted-out numbers (the suppression list).

read-only

Argument	Type	Description
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    }
  }
}

list_registration_submissions

The filed copies of a 10DLC registration, newest first.

read-only

Argument	Type	Description
id*	string	Registration id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Registration id"
    }
  }
}

list_registrations

List 10DLC brand and campaign registrations and their status. Marketing from a local number needs an approved one.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_scheduled_messages

List single messages scheduled for later and not yet sent.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_schedules

List recurring schedules.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_segments

List saved segments.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_templates

List message templates.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_toll_free_verifications

List toll-free verifications and their status (draft, in_review with our team, submitted to the carriers, verified, rejected). A toll-free number texts the public only once verified.

read-only

Argument	Type	Description
limit	integer
cursor	string	next_cursor from the previous page
status	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 1
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    },
    "status": {
      "enum": [
        "draft",
        "in_review",
        "submitted",
        "verified",
        "rejected"
      ],
      "type": "string"
    }
  }
}

list_topics

List subscription topics.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_webhook_deliveries

Delivery attempts to your webhook endpoints, with response status codes.

read-only

Argument	Type	Description
limit	number	Max results (default 25, max 100)
cursor	string	next_cursor from the previous page
event_id	string	Every attempt for one event
endpoint_id	string	One endpoint (we_...), or status_callback for the attempts to send messages' own status callbacks.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    },
    "event_id": {
      "type": "string",
      "description": "Every attempt for one event"
    },
    "endpoint_id": {
      "type": "string",
      "description": "One endpoint (we_...), or status_callback for the attempts to send messages' own status callbacks."
    }
  }
}

list_webhooks

List webhook endpoints.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

lookup_phone

Look up line type (mobile, landline, VoIP) and carrier for any US/Canada number.

read-only

Argument	Type	Description
phone*	string	E.164 number

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone"
  ],
  "properties": {
    "phone": {
      "type": "string",
      "description": "E.164 number"
    }
  }
}

pause_automation

Pause an automation: no new runs start, and runs in progress wait where they are until it is activated again.

destructive

Argument	Type	Description
id*	string	Automation id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    }
  }
}

pause_batch

Pause a sending or scheduled batch.

destructive

Argument	Type	Description
id*	string	Batch id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    }
  }
}

plan_import

Find out where an audience is and the ways to bring it in. Without source: questions to ask the person (where their people are, which group, what they can sign in to, whether consent was recorded, once or kept in sync) and the kinds of source known. With source (their words, e.g. "Mixpanel", "Shopify", "our Postgres users table", "a Google Sheet"): the ways in, best first, each with steps and a console link: an integration already syncing it, tools already in this chat for it, a 6-hourly sync connected with their key here or in the console, a push to an ingest URL, a script with a key from their environment, an export, or a CSV upload. Changes nothing.

read-only

Argument	Type	Description
source	string	Where the people are, in your words. Omit to get the questions first.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Where the people are, in your words. Omit to get the questions first."
    }
  }
}

preview_segment

Count the contacts a segment matches right now and how many a broadcast would reach (opted-out contacts removed, and with topic_id those unsubscribed from it).

read-only

Argument	Type	Description
id*	string	Segment id
topic_id	string	Count only contacts subscribed to this topic

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Segment id"
    },
    "topic_id": {
      "type": "string",
      "description": "Count only contacts subscribed to this topic"
    }
  }
}

purchase_number

Buy a phone number for your account (free sandbox numbers with test keys). Live numbers are billed monthly.

destructive

Argument	Type	Description
customer_id	string	Optional: assign the number to one of your customers
phone_number*	string
idempotency_key	string	Optional. 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.
registration_id	string	Optional (live numbers): the registration this number should send for. Without it the number follows your account's registration.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_number"
  ],
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Optional: assign the number to one of your customers"
    },
    "phone_number": {
      "type": "string"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional. 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."
    },
    "registration_id": {
      "type": "string",
      "description": "Optional (live numbers): the registration this number should send for. Without it the number follows your account's registration."
    }
  }
}

query_audience

Count a cohort without saving anything (nothing appears in the console): run up to 10 segment rules now and get the counts (matched, opted out, eligible to text) and the first contacts. Examples: replied in the last 7 days (last_reply_at after 7d); got a batch and did not reply (batch sent, and batch replied with is_not); started checkout but never purchased (event exists, event not_exists); VIPs not texted in 30 days. Same rule fields as a saved segment. Everyone eligible to text: one rule, status is subscribed.

destructive

Argument	Type	Description
limit	integer	How many matching contacts to return
match	string
rules	array
topic_id	string	Topic id or name: eligible also removes contacts unsubscribed from it

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 0,
      "description": "How many matching contacts to return"
    },
    "match": {
      "enum": [
        "all",
        "any"
      ],
      "type": "string",
      "default": "all"
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "field"
        ],
        "properties": {
          "op": {
            "enum": [
              "is",
              "is_not",
              "contains",
              "not_contains",
              "exists",
              "not_exists",
              "before",
              "after"
            ],
            "type": "string",
            "description": "Text fields take is / is_not / contains / not_contains / exists / not_exists; tag takes is / is_not / exists / not_exists; status, topic, import, batch and list take is / is_not; created_at takes before / after; last_message_at, last_reply_at and event take after (at or after the time), before (it happened, and the last time was before it), exists (ever) and not_exists (never). Comparisons ignore case."
          },
          "key": {
            "type": "string",
            "description": "The custom field name (field), topic id (topic), batch id (batch), or event name (event)"
          },
          "field": {
            "enum": [
              "tag",
              "first_name",
              "last_name",
              "name",
              "email",
              "company",
              "state",
              "source",
              "field",
              "import",
              "status",
              "topic",
              "created_at",
              "last_message_at",
              "last_reply_at",
              "batch",
              "event",
              "list"
            ],
            "type": "string",
            "description": "Attributes: tag, the name and profile fields, source, field (a custom field), import, status (opt-out), topic, list (in a static list), created_at. Behaviour: last_message_at (last text either way), last_reply_at (last text from them), batch (what happened to them in one batch), event (a tracked event; the newest 20,000 events are searched)."
          },
          "value": {
            "type": "string",
            "description": "status: subscribed or opted_out. topic: subscribed or unsubscribed. import: an import id. list: a list id (lst_...). batch: included, sent, failed, skipped or replied (sent, then texted the batch's number after it was created). Times (created_at, last_message_at, last_reply_at, event): an ISO date, or a window back from now such as 7d or 24h, read each time the segment is used."
          }
        }
      },
      "maxItems": 10
    },
    "topic_id": {
      "type": "string",
      "description": "Topic id or name: eligible also removes contacts unsubscribed from it"
    }
  }
}

redact_message

Empty a finished message's text and media everywhere it is kept, keeping its status, price and timeline (redacted_at is set). Cannot be undone.

destructive

Argument	Type	Description
id*	string	Message id (msg_...)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Message id (msg_...)"
    }
  }
}

release_number

Release a number you own. It cannot be got back.

destructive

Argument	Type	Description
phone_number*	string	E.164 number you own

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_number"
  ],
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "E.164 number you own"
    }
  }
}

remove_from_list

Remove contacts from a list (they stay contacts).

destructive

Argument	Type	Description
id*	string	List id
contact_ids	array
phone_numbers	array

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id"
    },
    "contact_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "phone_numbers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

replay_event

Send an event again to one webhook endpoint (after fixing the receiver).

destructive

Argument	Type	Description
id*	string	Event id
endpoint_id*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "endpoint_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Event id"
    },
    "endpoint_id": {
      "type": "string"
    }
  }
}

replay_failed_webhooks

Re-send every event that failed to reach a webhook endpoint in a window (default the last 24 hours, up to 7 days), after fixing the receiver.

destructive

Argument	Type	Description
id*	string	Webhook endpoint id
since	string	ISO date or epoch milliseconds. Default: 24 hours before `until`.
until	string	ISO date or epoch milliseconds. Default: now.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Webhook endpoint id"
    },
    "since": {
      "type": "string",
      "format": "date-time",
      "description": "ISO date or epoch milliseconds. Default: 24 hours before `until`."
    },
    "until": {
      "type": "string",
      "format": "date-time",
      "description": "ISO date or epoch milliseconds. Default: now."
    }
  }
}

request_short_code

Ask our team for a short code (or a toll-free number they set up). Provisions nothing by itself; carriers take 8-12 weeks to approve a short code.

destructive

Argument	Type	Description
type*	string
use_case*	string	What you will send, in a sentence or two.
business_name*	string
monthly_volume*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "type",
    "business_name",
    "monthly_volume",
    "use_case"
  ],
  "properties": {
    "type": {
      "enum": [
        "short_code",
        "toll_free"
      ],
      "type": "string"
    },
    "use_case": {
      "type": "string",
      "maxLength": 500,
      "minLength": 10,
      "description": "What you will send, in a sentence or two."
    },
    "business_name": {
      "type": "string",
      "maxLength": 120
    },
    "monthly_volume": {
      "enum": [
        "under_1k",
        "1k_10k",
        "10k_100k",
        "over_100k"
      ],
      "type": "string"
    }
  }
}

resume_batch

Resume a paused batch.

destructive

Argument	Type	Description
id*	string	Batch id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    }
  }
}

retry_batch

Retry a batch's failed recipients.

destructive

Argument	Type	Description
id*	string	Batch id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Batch id"
    }
  }
}

revoke_api_key

Revoke an API key of this mode. Immediate and permanent: anything using it stops working.

destructive

Argument	Type	Description
id*	string	API key id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "API key id"
    }
  }
}

rotate_webhook_secret

Replace a webhook endpoint's signing secret (returned once). expire_previous_in keeps the old one signing for that many seconds so the receiver can switch without dropping events.

destructive

Argument	Type	Description
id*	string	Webhook endpoint id
expire_previous_in	integer	Seconds the old secret keeps signing alongside the new one.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Webhook endpoint id"
    },
    "expire_previous_in": {
      "type": "integer",
      "default": 0,
      "maximum": 604800,
      "minimum": 0,
      "description": "Seconds the old secret keeps signing alongside the new one."
    }
  }
}

search_available_numbers

Search purchasable numbers by area code (default 415).

read-only

Argument	Type	Description
area_code	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "area_code": {
      "type": "string"
    }
  }
}

send_batch

Send one message to many people (a broadcast or campaign): pick recipients by segment_id, tags, contact_ids, or an explicit recipients list. Opted-out numbers, numbers without marketing consent, and people unsubscribed from topic_id are removed before sending. dry_run: true sends nothing and returns the count, cost, rejected rows and consent.no_opt_in (recipients the send will skip for having no opt-in). scheduled_at sends later (up to 30 days). With a live key it texts real people.

destructive

Argument	Type	Description
body*	string
from	string	One of your numbers. Optional while the key's mode has one number.
name	string
tags	array	Send to contacts carrying any of these tags (instead of recipients).
dry_run	boolean	Validate only: returns a BatchValidation and sends nothing.
list_id	string	Send to the contacts in this list, as it is when the batch is created (instead of recipients).
category	string	Optional. It can make the batch stricter (`marketing`), never looser: the sending number's registration and the wording decide ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing)). From a number with no registration, a batch is marketing.

send_message

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 (8pm in Florida, Maryland and Oklahoma) in the recipient's local time a marketing message is refused and anything else is held until 8am, 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).

destructive

Argument	Type	Description
to*	string
body*	string
from	string	One 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.
tags	array	Optional. 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=.
media	array	Reserved for MMS; currently returns 400 mms_not_enabled.
consent	object

send_verification

Send a one-time verification code (OTP) to a phone number by text, or to an email address with channel "email". TextKit generates the code, handles expiry (10 min) and attempt limits (5), and blocks SMS-pumping and email-bombing abuse.

destructive

Argument	Type	Description
from	string	Optional, channel `sms` only: send from a number you own instead of the TextKit pool
email	string	The address to email the code to (channel `email`). Disposable addresses are refused.
phone	string	The number to text the code to (channel `sms`). `to` works too.
channel	string	How the code goes out. `sms` needs `phone`; `email` needs `email`.
user_ip	string	Optional. Your end user's IP address, as your server saw it. With it, one person requesting codes for many numbers or addresses is limited (20 an hour per IP on your account, texts and emails together); without it there is no per-IP limit, since requests come from your server.
app_name	string	Your product name, shown in the message
customer_id	string	Optional: attribute the verification to one of your customers

set_consent

Record an opt-in or opt-out from your own system (CRM, checkout, a form). An opt-in for a marketing registration needs proof (source, when, the page).

destructive

Argument	Type	Description
note	string
phone*	string	E.164 number
proof	object	Opt-in evidence (Messaging Policy 1.4). Accepted only with status opted_in.
status*	string
campaign_id	string	Only with opted_in: the registration the person opted in to. A marketing send from a number linked to that registration looks for this record. Proof is required when its use case is marketing or mixed (400 otherwise). An opt-out is always account-wide.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone",
    "status"
  ],
  "properties": {
    "note": {
      "type": "string",
      "maxLength": 200
    },
    "phone": {
      "type": "string",
      "description": "E.164 number"
    },
    "proof": {
      "type": "object",
      "required": [
        "source"
      ],
      "properties": {
        "ip": {
          "type": "string"
        },
        "source": {
          "enum": [
            "web_form",
            "keyword",
            "paper",
            "checkout",
            "verbal"
          ],
          "type": "string"
        },
        "page_url": {
          "type": "string",
          "format": "uri",
          "description": "Required for web_form"
        },
        "disclosure": {
          "type": "string",
          "maxLength": 2000,
          "description": "Exact disclosure wording shown"
        },
        "message_id": {
          "type": "string",
          "description": "The inbound message that was the opt-in. Required for keyword opt-ins recorded for a marketing registration"
        },
        "user_agent": {
          "type": "string",
          "maxLength": 500
        },
        "campaign_id": {
          "type": "string"
        },
        "collected_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the person consented; defaults to now"
        },
        "registration_id": {
          "type": "string"
        }
      },
      "description": "Opt-in evidence (Messaging Policy 1.4). Accepted only with status opted_in."
    },
    "status": {
      "enum": [
        "opted_out",
        "opted_in"
      ],
      "type": "string"
    },
    "campaign_id": {
      "type": "string",
      "description": "Only with opted_in: the registration the person opted in to. A marketing send from a number linked to that registration looks for this record. Proof is required when its use case is marketing or mixed (400 otherwise). An opt-out is always account-wide."
    }
  }
}

set_contact_topic

Subscribe a contact to a topic, or unsubscribe them (e.g. "promotions" vs "order updates").

destructive

Argument	Type	Description
id*	string	Contact id
topic*	string	Topic id (see list_topics)
source	string	Where the change came from, e.g. "preference_page". Default "api".
subscribed*	boolean

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "topic",
    "subscribed"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Contact id"
    },
    "topic": {
      "type": "string",
      "description": "Topic id (see list_topics)"
    },
    "source": {
      "type": "string",
      "description": "Where the change came from, e.g. \"preference_page\". Default \"api\"."
    },
    "subscribed": {
      "type": "boolean"
    }
  }
}

set_spend_limit

Set or remove the monthly spend cap and its alert thresholds. Live sends over the cap are refused.

destructive

Argument	Type	Description
alert_thresholds	array
monthly_limit_usd	number	null removes the cap

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "alert_thresholds": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 100,
        "minimum": 1
      },
      "maxItems": 5
    },
    "monthly_limit_usd": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 1,
      "nullable": true,
      "description": "null removes the cap"
    }
  }
}

simulate_inbound

Sandbox only: simulate an inbound SMS to one of your test numbers (emits message.received; STOP, START and HELP act as for real).

destructive

Argument	Type	Description
to	string	One of your sandbox numbers (never a live number). Optional while the account has one sandbox number.
body*	string
from*	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "from",
    "body"
  ],
  "properties": {
    "to": {
      "type": "string",
      "description": "One of your sandbox numbers (never a live number). Optional while the account has one sandbox number."
    },
    "body": {
      "type": "string"
    },
    "from": {
      "type": "string"
    }
  }
}

sync_integration

Sync a connected tool now (up to 6 times an hour) and get what changed.

destructive

Argument	Type	Description
id*	string	Integration id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Integration id"
    }
  }
}

test_webhook

Send a signed test.ping to a webhook endpoint and see what it answered.

destructive

Argument	Type	Description
id*	string	Webhook endpoint id

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Webhook endpoint id"
    }
  }
}

track_event

Record something a customer did (e.g. signed_up, cart_abandoned, trial_ending), by user_id and/or phone. It starts or advances any active automation listening for that event.

destructive

Argument	Type	Description
event*	string	Letters, digits, and _ . : -
phone	string
user_id	string
properties	object	Up to 20 scalar values; usable as merge fields and in conditions.
idempotency_key	string	Optional. A unique key for this call: a retry with the same key is recorded once.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "event"
  ],
  "properties": {
    "event": {
      "type": "string",
      "maxLength": 64,
      "description": "Letters, digits, and _ . : -"
    },
    "phone": {
      "type": "string"
    },
    "user_id": {
      "type": "string",
      "maxLength": 128
    },
    "properties": {
      "type": "object",
      "description": "Up to 20 scalar values; usable as merge fields and in conditions."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional. A unique key for this call: a retry with the same key is recorded once."
    }
  }
}

update_automation

Edit an automation (name, sender, trigger, or steps).

destructive

Argument	Type	Description
id*	string	Automation id
from	string	One of your numbers. A sandbox number makes it a sandbox flow.
name	string
steps	array
trigger	object
topic_id	string	Skip recipients unsubscribed from this topic.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Automation id"
    },
    "from": {
      "type": "string",
      "nullable": true,
      "description": "One of your numbers. A sandbox number makes it a sandbox flow."
    },
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable handle for goto branches; assigned when omitted."
          },
          "body": {
            "type": "string",
            "maxLength": 1600,
            "description": "send_sms. Merge fields: event properties by name, {{first_name}}, {{name}}, {{phone}}, {{field:<custom>}}."
          },
          "from": {
            "type": "string",
            "description": "send_sms: overrides the flow sender."
          },
          "type": {
            "enum": [
              "send_sms",
              "wait",
              "wait_for_event",
              "condition",
              "end"
            ],
            "type": "string"
          },
          "check": {
            "type": "object",
            "description": "{kind: event_received, event} | {kind: property, property, op, value?} | {kind: contact_field, field, op, value?}. op: eq, neq, contains, gt, lt, exists, not_exists."
          },
          "event": {
            "type": "string"
          },
          "on_met": {
            "type": "string"
          },
          "seconds": {
            "type": "integer",
            "maximum": 2592000,
            "minimum": 60
          },
          "on_not_met": {
            "type": "string"
          },
          "on_timeout": {
            "type": "string"
          },
          "on_received": {
            "type": "string"
          },
          "timeout_seconds": {
            "type": "integer",
            "maximum": 2592000,
            "minimum": 60
          }
        },
        "description": "One of: send_sms {body, from?}; wait {seconds}; wait_for_event {event, timeout_seconds, on_received, on_timeout}; condition {check, on_met, on_not_met}; end. Branches are \"continue\", \"end\", or \"goto:<id of a later step>\"."
      },
      "maxItems": 20
    },
    "trigger": {
      "type": "object",
      "properties": {
        "event": {
          "type": "string"
        },
        "filters": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "op": {
                "type": "string"
              },
              "value": {},
              "property": {
                "type": "string"
              }
            }
          },
          "maxItems": 5
        }
      }
    },
    "topic_id": {
      "type": "string",
      "nullable": true,
      "description": "Skip recipients unsubscribed from this topic."
    }
  }
}

update_contact

Update a contact. Only the inputs you pass change; tags and fields replace the whole list or map.

destructive

Argument	Type	Description
id*	string	Contact id
name	string
tags	array
email	string
notes	string
state	string
fields	object	Up to 20 string values
source	string
company	string
last_name	string
first_name	string
phone_number

update_customer

Rename a customer or change its external_id or metadata.

destructive

Argument	Type	Description
id*	string	Customer id
name	string
metadata	object	Up to 50 string values
external_id	string	Your id for them; unique per account

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer id"
    },
    "name": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    },
    "metadata": {
      "type": "object",
      "description": "Up to 50 string values",
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "external_id": {
      "type": "string",
      "nullable": true,
      "maxLength": 200,
      "description": "Your id for them; unique per account"
    }
  }
}

update_integration

Rename, pause or resume (status), or change an integration's settings or credentials (left-out credentials keep the stored ones).

destructive

Argument	Type	Description
id*	string	Integration id
name	string
apiKey	string
secret	string
status	string
sourceId	string
username	string
secretKey	string
phoneEvent	string
phoneField	string
accessToken	string

update_list

Rename a list or change its description.

destructive

Argument	Type	Description
id*	string	List id
name	string
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id"
    },
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}

update_number_pool

Rename a sender pool or change its numbers.

destructive

Argument	Type	Description
id*	string	Pool id
name	string
routing	string	How a recipient gets a number. sticky: the same member every time. local: a member in the recipient's area code, else one in their time zone, else any; still the same one each time.
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Pool id"
    },
    "name": {
      "type": "string"
    },
    "routing": {
      "enum": [
        "sticky",
        "local"
      ],
      "type": "string",
      "default": "sticky",
      "description": "How a recipient gets a number. sticky: the same member every time. local: a member in the recipient's area code, else one in their time zone, else any; still the same one each time."
    },
    "description": {
      "type": "string"
    }
  }
}

update_schedule

Pause (active: false) or resume (active: true) a recurring schedule.

destructive

Argument	Type	Description
id*	string	Schedule id
active	boolean	false pauses, true resumes.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Schedule id"
    },
    "active": {
      "type": "boolean",
      "description": "false pauses, true resumes."
    }
  }
}

update_segment

Rename a segment or replace its rules.

destructive

Argument	Type	Description
id*	string	Segment id
name	string
match	string
rules	array
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Segment id"
    },
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "match": {
      "enum": [
        "all",
        "any"
      ],
      "type": "string",
      "default": "all"
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "field"
        ],
        "properties": {
          "op": {
            "enum": [
              "is",
              "is_not",
              "contains",
              "not_contains",
              "exists",
              "not_exists",
              "before",
              "after"
            ],
            "type": "string",
            "description": "Text fields take is / is_not / contains / not_contains / exists / not_exists; tag takes is / is_not / exists / not_exists; status, topic, import, batch and list take is / is_not; created_at takes before / after; last_message_at, last_reply_at and event take after (at or after the time), before (it happened, and the last time was before it), exists (ever) and not_exists (never). Comparisons ignore case."
          },
          "key": {
            "type": "string",
            "description": "The custom field name (field), topic id (topic), batch id (batch), or event name (event)"
          },
          "field": {
            "enum": [
              "tag",
              "first_name",
              "last_name",
              "name",
              "email",
              "company",
              "state",
              "source",
              "field",
              "import",
              "status",
              "topic",
              "created_at",
              "last_message_at",
              "last_reply_at",
              "batch",
              "event",
              "list"
            ],
            "type": "string",
            "description": "Attributes: tag, the name and profile fields, source, field (a custom field), import, status (opt-out), topic, list (in a static list), created_at. Behaviour: last_message_at (last text either way), last_reply_at (last text from them), batch (what happened to them in one batch), event (a tracked event; the newest 20,000 events are searched)."
          },
          "value": {
            "type": "string",
            "description": "status: subscribed or opted_out. topic: subscribed or unsubscribed. import: an import id. list: a list id (lst_...). batch: included, sent, failed, skipped or replied (sent, then texted the batch's number after it was created). Times (created_at, last_message_at, last_reply_at, event): an ISO date, or a window back from now such as 7d or 24h, read each time the segment is used."
          }
        }
      },
      "maxItems": 10
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}

update_template

Rename or edit a template.

destructive

Argument	Type	Description
id*	string	Template id
body	string
name	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Template id"
    },
    "body": {
      "type": "string",
      "maxLength": 1600
    },
    "name": {
      "type": "string",
      "maxLength": 60
    }
  }
}

update_topic

Rename or describe a topic.

destructive

Argument	Type	Description
id*	string	Topic id
name	string
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Topic id"
    },
    "name": {
      "type": "string",
      "maxLength": 60
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}

update_webhook

Change a webhook endpoint: URL, events, or turn it off (active: false).

destructive

Argument	Type	Description
id*	string	Webhook endpoint id
url	string
active	boolean	false pauses delivery; pending retries for a paused endpoint are dropped.
events	any
numbers	array	Replace the number filter; [] or null clears it.
description	string

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Webhook endpoint id"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "active": {
      "type": "boolean",
      "description": "false pauses delivery; pending retries for a paused endpoint are dropped."
    },
    "events": {
      "oneOf": [
        {
          "enum": [
            "*"
          ],
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "numbers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "nullable": true,
      "description": "Replace the number filter; [] or null clears it."
    },
    "description": {
      "type": "string",
      "nullable": true,
      "maxLength": 120
    }
  }
}

upsert_contact

Create a contact, or update the existing one with the same phone_number.

destructive

Argument	Type	Description
name	string	Display name. Defaults to first + last name.
tags	array
email	string
notes	string
state	string
fields	object	Up to 20 string values (account id, plan, location...), usable in segments and as {{field:key}} merge fields
opt_in	object	Import only (POST /v1/contacts/import). Stored as consent evidence; never lifts an opt-out.
source	string	Where the contact came from. Defaults to "api".
company	string
last_name	string

verify_link_domain

Check a link domain's DNS records now. When both are found it is turned on (active) at once.

destructive

Argument	Type	Description
id*	string	Link domain id (ld_...)

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Link domain id (ld_...)"
    }
  }
}

wait_for_events

Wait up to 25 seconds for the next events after a cursor (a reply, a delivery receipt), then return them.

read-only

Argument	Type	Description
cursor	string	The `cursor` of the previous response. Omit on the first call.
timeout	integer	Seconds to hold the request.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "description": "The `cursor` of the previous response. Omit on the first call."
    },
    "timeout": {
      "type": "integer",
      "default": 20,
      "maximum": 25,
      "minimum": 0,
      "description": "Seconds to hold the request."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "provider"
  ],
  "properties": {
    "mode": {
      "enum": [
        "pull",
        "push"
      ],
      "type": "string",
      "description": "Mixpanel / Amplitude: pull with credentials every 6 hours (default when credentials are sent), or push: no credentials, the tool's cohort sync posts to the ingest URL."
    },
    "name": {
      "type": "string",
      "description": "What to call it (default: the tool and its source)."
    },
    "apiKey": {
      "type": "string",
      "description": "Amplitude API key."
    },
    "region": {
      "enum": [
        "us",
        "eu"
      ],
      "type": "string",
      "description": "Mixpanel / Amplitude data residency."
    },
    "secret": {
      "type": "string",
      "description": "Mixpanel service account secret."
    },
    "clientId": {
      "type": "string",
      "description": "Salesforce consumer key, or Shopify client id."
    },
    "provider": {
      "enum": [
        "shopify",
        "hubspot",
        "salesforce",
        "mixpanel",
        "amplitude",
        "webhook"
      ],
      "type": "string"
    },
    "sfObject": {
      "enum": [
        "Contact",
        "Lead"
      ],
      "type": "string"
    },
    "sourceId": {
      "type": "string",
      "description": "Mixpanel or Amplitude cohort id; HubSpot list id; Salesforce campaign id; a Shopify customer search. Blank = everyone (HubSpot, Shopify, Salesforce)."
    },
    "username": {
      "type": "string",
      "description": "Mixpanel service account username."
    },
    "projectId": {
      "type": "string",
      "description": "Mixpanel project id."
    },
    "secretKey": {
      "type": "string",
      "description": "Amplitude secret key."
    },
    "phoneEvent": {
      "type": "string",
      "description": "Mixpanel: an event that carries the number when profiles do not (e.g. Verification Check Success). A member with no phone on the profile gets it from their latest such event."
    },
    "phoneField": {
      "type": "string",
      "description": "The tool's property holding the mobile number, when not the usual one ($phone, phone, mobilephone)."
    },
    "shopDomain": {
      "type": "string",
      "description": "Shopify store, like acme.myshopify.com."
    },
    "accessToken": {
      "type": "string",
      "description": "HubSpot private app token, or Shopify Admin API access token."
    },
    "instanceUrl": {
      "type": "string",
      "description": "Salesforce My Domain URL."
    },
    "clientSecret": {
      "type": "string",
      "description": "Salesforce consumer secret, or Shopify client secret."
    },
    "consentEvent": {
      "type": "string",
      "description": "Mixpanel / Amplitude: the opt-in event the cohort is built on (e.g. SMS Opt In). Everyone in the cohort is recorded as opted in, from that event."
    },
    "consentField": {
      "type": "string",
      "description": "The tool's property that records SMS consent (e.g. sms_opt_in)."
    },
    "phoneEventProperty": {
      "type": "string",
      "description": "Mixpanel: that event's property holding the number (default phone)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "to",
    "body",
    "repeat"
  ],
  "properties": {
    "to": {
      "type": "string"
    },
    "body": {
      "type": "string",
      "maxLength": 1600
    },
    "from": {
      "type": "string",
      "description": "One of your numbers. Optional when the account has exactly one number for the key's mode."
    },
    "repeat": {
      "type": "object",
      "required": [
        "frequency",
        "time",
        "timezone"
      ],
      "properties": {
        "time": {
          "type": "string",
          "description": "24-hour wall-clock time, HH:MM, in `timezone`."
        },
        "timezone": {
          "type": "string",
          "description": "IANA time zone."
        },
        "frequency": {
          "enum": [
            "daily",
            "weekly",
            "monthly"
          ],
          "type": "string"
        },
        "day_of_month": {
          "type": "integer",
          "maximum": 31,
          "minimum": 1,
          "description": "Monthly only, required. Months without that day run on their last day."
        },
        "days_of_week": {
          "type": "array",
          "items": {
            "enum": [
              "sun",
              "mon",
              "tue",
              "wed",
              "thu",
              "fri",
              "sat"
            ],
            "type": "string"
          },
          "description": "Weekly only, required: which weekdays."
        }
      }
    },
    "category": {
      "enum": [
        "marketing",
        "transactional",
        "otp"
      ],
      "type": "string",
      "nullable": true,
      "description": "Optional. It can make each occurrence stricter (`marketing`), never looser: the sending number's registration and the wording decide ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing))."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "nullable": true,
      "description": "Last local date it may run (inclusive)."
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "nullable": true,
      "description": "First local date it may run. Defaults to today."
    },
    "quiet_hours": {
      "enum": [
        "block",
        "defer"
      ],
      "type": "string",
      "nullable": true,
      "description": "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: an occurrence in quiet hours is held until the recipient's 8:00am and recorded as `deferred`."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional. 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."
    },
    "max_occurrences": {
      "type": "integer",
      "minimum": 1,
      "nullable": true,
      "description": "The schedule completes after this many messages have been sent."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "kind"
  ],
  "properties": {
    "q": {
      "type": "string",
      "description": "messages: body/failure text; events: id/payload text"
    },
    "ok": {
      "type": "boolean",
      "description": "webhook_deliveries"
    },
    "to": {
      "type": "string",
      "description": "Inclusive; a bare date means the end of that day (UTC)"
    },
    "from": {
      "type": "string",
      "description": "ISO date/time or epoch ms (messages, deliveries, events, webhook_deliveries)"
    },
    "kind": {
      "type": "string",
      "description": "messages, deliveries, events, opt_outs, webhook_deliveries, usage, usage_monthly, audit_log or credit_history"
    },
    "type": {
      "type": "string",
      "description": "events, webhook_deliveries"
    },
    "actor": {
      "type": "string",
      "description": "audit_log: actor id or part of the actor email"
    },
    "batch": {
      "type": "string",
      "description": "messages, deliveries: batch id (bc_...)"
    },
    "action": {
      "type": "string",
      "description": "audit_log: one action, or a group prefix with a trailing dot (team.)"
    },
    "months": {
      "type": "integer",
      "default": 3,
      "maximum": 12,
      "minimum": 1,
      "description": "usage: daily rows for the last N months"
    },
    "number": {
      "type": "string",
      "description": "messages, deliveries: digits matched against either side"
    },
    "status": {
      "enum": [
        "queued",
        "sent",
        "delivered",
        "failed",
        "blocked",
        "received"
      ],
      "type": "string",
      "description": "messages, deliveries"
    },
    "direction": {
      "enum": [
        "outbound",
        "inbound"
      ],
      "type": "string",
      "description": "messages"
    },
    "to_number": {
      "type": "string",
      "description": "messages, deliveries: exact recipient (E.164). `to`/`from` are the date range here."
    },
    "customer_id": {
      "type": "string",
      "description": "messages, deliveries"
    },
    "endpoint_id": {
      "type": "string",
      "description": "webhook_deliveries (default: all endpoints)"
    },
    "from_number": {
      "type": "string",
      "description": "messages, deliveries: exact sender (E.164)"
    },
    "target_type": {
      "type": "string",
      "description": "audit_log"
    },
    "failure_code": {
      "enum": [
        "carrier_filtered",
        "unreachable",
        "invalid_number",
        "opted_out",
        "campaign_mismatch",
        "content_blocked",
        "screen_unavailable",
        "rate_limited",
        "landline",
        "carrier_rejected",
        "spend_limit_reached",
        "insufficient_credits",
        "sender_not_registered",
        "quiet_hours",
        "consent_required",
        "reconfirmation_pending",
        "reconfirmation_expired",
        "held_for_review",
        "review_rejected",
        "review_expired",
        "campaign_paused",
        "sender_rotation",
        "recipient_not_verified",
        "quota_exceeded",
        "destination_not_allowed",
        "account_closed",
        "account_suspended",
        "account_paused",
        "topic_unsubscribed",
        "unknown"
      ],
      "type": "string",
      "description": "messages, deliveries: failed for this reason (the `failure.code` on a message)"
    },
    "created_after": {
      "type": "string",
      "description": "audit_log: same as on GET /audit-logs (from is accepted too)"
    },
    "blocked_reason": {
      "type": "string",
      "description": "messages, deliveries: blocked messages with this reason"
    },
    "created_before": {
      "type": "string",
      "description": "audit_log: same as on GET /audit-logs (to is accepted too)"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "description": "Exact destination number (E.164)"
    },
    "tag": {
      "type": "string",
      "description": "Filter to messages sent with this tag"
    },
    "from": {
      "type": "string",
      "description": "Exact sending number (E.164)"
    },
    "limit": {
      "type": "number",
      "description": "Max results (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page"
    },
    "number": {
      "type": "string",
      "description": "Filter to messages to or from this number"
    },
    "status": {
      "enum": [
        "queued",
        "sent",
        "delivered",
        "failed",
        "blocked",
        "received"
      ],
      "type": "string"
    },
    "direction": {
      "enum": [
        "outbound",
        "inbound"
      ],
      "type": "string"
    },
    "customer_id": {
      "type": "string",
      "description": "Filter to one customer's messages"
    },
    "schedule_id": {
      "type": "string",
      "description": "Filter to the occurrences of one recurring schedule (sch_...)"
    },
    "failure_code": {
      "enum": [
        "carrier_filtered",
        "unreachable",
        "invalid_number",
        "opted_out",
        "campaign_mismatch",
        "content_blocked",
        "screen_unavailable",
        "rate_limited",
        "landline",
        "carrier_rejected",
        "spend_limit_reached",
        "insufficient_credits",
        "sender_not_registered",
        "quiet_hours",
        "consent_required",
        "reconfirmation_pending",
        "reconfirmation_expired",
        "held_for_review",
        "review_rejected",
        "review_expired",
        "campaign_paused",
        "sender_rotation",
        "recipient_not_verified",
        "quota_exceeded",
        "destination_not_allowed",
        "account_closed",
        "account_suspended",
        "account_paused",
        "topic_unsubscribed",
        "unknown"
      ],
      "type": "string",
      "description": "Filter to messages that failed for this reason (the `failure.code` on a message)"
    },
    "created_after": {
      "type": "string",
      "description": "Inclusive. ISO timestamp or epoch ms."
    },
    "blocked_reason": {
      "enum": [
        "account_closed",
        "account_suspended",
        "account_paused",
        "opted_out",
        "destination_not_allowed",
        "sender_not_registered",
        "campaign_mismatch",
        "rate_limited",
        "recipient_not_verified",
        "quiet_hours",
        "consent_required",
        "reconfirmation_pending",
        "reconfirmation_expired",
        "campaign_paused",
        "sender_rotation",
        "content_blocked",
        "screen_unavailable",
        "held_for_review",
        "review_rejected",
        "review_expired",
        "quota_exceeded",
        "spend_limit_reached",
        "insufficient_credits",
        "topic_unsubscribed"
      ],
      "type": "string",
      "description": "Blocked messages with this reason. Implies status=blocked."
    },
    "created_before": {
      "type": "string",
      "description": "Exclusive. ISO timestamp or epoch ms."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "body"
  ],
  "properties": {
    "body": {
      "type": "string",
      "maxLength": 1600
    },
    "from": {
      "type": "string",
      "description": "One of your numbers. Optional while the key's mode has one number."
    },
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Send to contacts carrying any of these tags (instead of recipients)."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Validate only: returns a BatchValidation and sends nothing."
    },
    "list_id": {
      "type": "string",
      "description": "Send to the contacts in this list, as it is when the batch is created (instead of recipients)."
    },
    "category": {
      "enum": [
        "marketing",
        "transactional",
        "otp"
      ],
      "type": "string",
      "description": "Optional. It can make the batch stricter (`marketing`), never looser: the sending number's registration and the wording decide ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing)). From a number with no registration, a batch is marketing."
    },
    "topic_id": {
      "type": "string",
      "description": "Subscription topic. Recipients unsubscribed from it are removed at validation (`topic_unsubscribed`) and skipped at send time, like opt-outs. Omit to apply opt-outs only."
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string"
          },
          "variables": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "maxItems": 10000
    },
    "segment_id": {
      "type": "string",
      "description": "Send to the contacts in this saved segment, evaluated when the batch is created (instead of recipients)."
    },
    "contact_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "quiet_hours": {
      "enum": [
        "block",
        "defer"
      ],
      "type": "string",
      "description": "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: each recipient in quiet hours is held until their 8:00am."
    },
    "scheduled_at": {
      "type": "string",
      "description": "Future ISO timestamp or epoch ms, up to 30 days out."
    },
    "check_line_types": {
      "type": "boolean",
      "description": "Reject landlines (first 500 unique numbers are checked)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "to",
    "body"
  ],
  "properties": {
    "to": {
      "type": "string"
    },
    "body": {
      "type": "string",
      "maxLength": 1600
    },
    "from": {
      "type": "string",
      "description": "One 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."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 32
      },
      "maxItems": 10,
      "description": "Optional. 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=."
    },
    "media": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "description": "Reserved for MMS; currently returns 400 mms_not_enabled."
    },
    "consent": {
      "type": "object",
      "required": [
        "source",
        "collected_at"
      ],
      "properties": {
        "source": {
          "enum": [
            "web_form",
            "keyword",
            "paper",
            "checkout",
            "verbal"
          ],
          "type": "string"
        },
        "page_url": {
          "type": "string",
          "format": "uri",
          "description": "Required for web_form: the page the form was on."
        },
        "collected_at": {
          "type": "string",
          "description": "When they agreed: ISO timestamp or epoch ms, not in the future."
        }
      },
      "description": "Optional. 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."
    },
    "category": {
      "enum": [
        "marketing",
        "transactional",
        "otp"
      ],
      "type": "string",
      "description": "Optional. 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_id": {
      "type": "string",
      "description": "Optional. 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_hours": {
      "enum": [
        "block",
        "defer"
      ],
      "type": "string",
      "description": "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."
    },
    "scheduled_at": {
      "type": "string",
      "description": "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."
    },
    "shorten_links": {
      "type": "boolean",
      "description": "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."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional. 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_callback": {
      "type": "string",
      "format": "uri",
      "description": "Optional. 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."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "phone_number"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 120,
      "description": "Display name. Defaults to first + last name."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      },
      "maxItems": 20
    },
    "email": {
      "type": "string",
      "maxLength": 254
    },
    "notes": {
      "type": "string",
      "maxLength": 2000
    },
    "state": {
      "type": "string",
      "maxLength": 40
    },
    "fields": {
      "type": "object",
      "description": "Up to 20 string values (account id, plan, location...), usable in segments and as {{field:key}} merge fields",
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "opt_in": {
      "type": "object",
      "properties": {
        "at": {
          "type": "string",
          "description": "When they opted in: ISO timestamp, date, or epoch ms"
        },
        "source": {
          "type": "string",
          "description": "web_form, keyword, paper, checkout or verbal are stored as proof; anything else is kept as a note"
        },
        "status": {
          "type": "boolean",
          "description": "true = opted in; false = unsubscribed (recorded as an opt-out)"
        },
        "page_url": {
          "type": "string",
          "format": "uri",
          "description": "The page a web-form opt-in was collected on"
        },
        "campaign_id": {
          "type": "string",
          "description": "The registration the opt-in is for. A marketing or mixed registration needs at, a recognised source, and page_url for a web form, or the row is skipped"
        }
      },
      "description": "Import only (POST /v1/contacts/import). Stored as consent evidence; never lifts an opt-out."
    },
    "source": {
      "type": "string",
      "maxLength": 60,
      "description": "Where the contact came from. Defaults to \"api\"."
    },
    "company": {
      "type": "string",
      "maxLength": 120
    },
    "last_name": {
      "type": "string",
      "maxLength": 80
    },
    "first_name": {
      "type": "string",
      "maxLength": 80
    },
    "phone_number": {
      "type": "string",
      "description": "E.164, US or Canada"
    }
  }
}