Textmagic

Retrieve paginated outbound (sent) SMS sessions for the current user, most recent first. A session is a single send operation that may target one or many recipients. Each session returns: the session ID (sessionId), when it was sent (sentAt), how many recipients it targeted (recipientsCount), how many messages were delivered (deliveredCount), the total amount for the session (totalCost, in the account `currency`), the sender ID or phone number it was sent from (fromNumber), the message type (messageType: text, tts, vbc or mms), and the text — the session text for multi-recipient sessions, or the actual SMS text when there is a single recipient. When a session has exactly one recipient, it also returns the individual message ID (messageId), its delivery status (messageStatus), a human-readable rejection reason if the message was rejected (rejectReason, null otherwise), the recipient phone number (phone), and the linked contact's name (contactName, null if the number is not linked to a contact). Use searchQuery to filter by message text or recipient phone number. Use get_inbound_sms_messages for received messages instead, or get_sms_chat_messages for a single conversation's full history. Page only when pagination.hasNextPage is true, passing pagination.lastId as the next lastId.

get_outbound_sms_sessions

Retrieve paginated SMS messages (both inbound and outbound) from a specific SMS chat. Returns up to 10 messages per page by default, ordered by most recent first. Only works with SMS chats — use search_sms_chats first to find the chatId. Does not mark messages as read. Excludes voice calls, notes, and non-SMS message types. Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of messages in the chat across all pages.

get_sms_chat_messages

Retrieve the individual outbound SMS messages that belong to a single sending session, identified by its session ID. A session may have sent to one or many recipients; this returns one entry per recipient. Each message returns: the message ID (messageId), the recipient phone number (phone), the linked contact's name (contactName, null if the number is not linked to a contact), the message text (text), the delivery status (status), a human-readable rejection reason if it was rejected (rejectReason, null otherwise), the amount (cost, in the account `currency`), and the number of SMS parts (parts). Use get_outbound_sms_sessions first to find the session ID. Use searchQuery to filter the recipients by message text or phone number. Returns up to 10 messages per page, ordered by recipient. Page only when pagination.hasNextPage is true, passing the next page number. pagination.totalCount is the total number of recipient messages in the session across all pages.

get_session_sms_messages

Retrieve the full details of a single scheduled (upcoming) SMS session by its ID. Returns everything list_sms_schedules returns (message text, amount — `cost`, in the account `currency` — parts count, recipients count, next send time, status and a human-readable recurrence description) plus three fields that the listing omits: the complete recipients breakdown (contactIds, groupIds, phoneNumbers, segmentIds), the structured recurrence rule (recurrentRule, null for one-time delayed sends), and previewDates — the next upcoming send times computed from the recurrence rule. Use list_sms_schedules first to find the schedule ID. Use this tool when you need the exact recipients, the structured recurrence rule, or the upcoming occurrences of a specific schedule — for example before editing or cancelling it. Only returns schedules with status "scheduled" that belong to the current account. Returns an error if no such schedule exists.

get_sms_schedule

List the contact segments (saved contact filter views) in the user's Textmagic account. Returns up to 10 segments per page, each with id, name, contactsCount, and a human-readable description of which filters the segment applies (entity references such as tags, lists, or countries are summarised by count, not expanded into individual IDs). Use this to discover a segment's ID before passing segmentId to search_contacts, preview_sms, or send_sms. A segment is a reusable filter over contacts (e.g. "VIP customers in the US"); it is NOT a static contact list — for lists/groups use search_lists instead. Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of segments across all pages. Returns an empty list when the account has no contact segments.

list_contact_segments

Returns all dynamic fields that can be embedded in an SMS message body to personalize the text per recipient. These are NOT contact tags/labels used for filtering — they are merge variables written as {Field name} inside the message text and replaced with each contact's data at send time. Two kinds are returned: - Standard fields: always available — {First name}, {Last name}, {Company name}, {Phone}, {Email}. - Custom field placeholders: account-specific fields the user has created for their contacts. Use this tool when the user asks what dynamic fields, merge variables, or personalization tokens are available for an SMS. Call preview_sms or send_sms with the field syntax in the `text` parameter to use them.

list_sms_dynamic_fields

List active (scheduled) SMS sessions for the current account — both one-time delayed sends and recurring messages. Returns only schedules with status "scheduled" (upcoming, not paused, not completed). Results are paginated, up to 10 per page, ordered by next send time (descending). Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of scheduled sessions across all pages. Each schedule includes its id, the message text, amount (cost, in the account `currency`), parts count, recipients count, next send time, status, and a human-readable recurrence description. To keep listings compact, the recipients breakdown is only included when the schedule targets a single recipient, and the structured recurrence rule and preview dates are omitted. Use this tool to review what recurring or delayed messages are set up and check their next send time. Call get_sms_schedule with a schedule id to retrieve the full recipients breakdown, the structured recurrence rule and the upcoming preview dates before editing or cancelling a schedule.

list_sms_schedules

Pause one or more scheduled (upcoming) SMS sessions by their IDs so they stop firing until resumed. Pausing does not delete the schedule and is reversible — a paused schedule keeps its recipients, message and recurrence rule and can be resumed later. Only schedules belonging to the current account are affected. Use list_sms_schedules to discover schedule IDs first. Returns an error if none of the given schedules could be paused — for example when they are already paused or do not exist in this account.

pause_sms_schedules

Preview an SMS before sending it. Returns character set, parts count, and a sample of up to 10 recipient messages so the user can review the content and recipients before sending. Amounts (`cost`, `price`) are in the account currency — see the `currency` field. HOW TO CALL — check every call against these rules: - Recipients (required): provide AT LEAST ONE of `contactIds`, `listId`, `segmentId`, or `phones`. You may combine them. - Message body (required): provide EXACTLY ONE of `text` OR `templateId`. Never send both; never send neither. * `text` — a raw message body you compose yourself. * `templateId` — the ID of an existing SMS template. - `scheduleToken` (optional): include ONLY for a delayed/recurring send; omit it for an immediate send. - Omit every field you are not using. Do NOT fill unused fields with placeholder values such as 0, 1, or "". If the message text contains dynamic contact fields such as {First name} or {Last name}, the preview returns per-recipient resolved texts; otherwise it returns a single representative parts count. US and Canadian recipients require a registered sender (a verified 10DLC campaign for the US, a verified toll-free number for either). When the account has none and every recipient is in the US/Canada, the preview fails and returns a link to the sender settings; when only some recipients are there, the preview succeeds and carries a `warning` field with the same link — relay it to the user verbatim. The returned `previewId` must be passed to the `send_sms` tool to perform the actual send. A preview expires after 30 minutes. To schedule a delayed or recurring send, first call create_recurring_schedule and pass the returned `scheduleToken` here. The preview then includes the schedule (rrule, description, and up to 5 upcoming send datetimes, recomputed live); the amount shown reflects a single run. Omit `scheduleToken` for an immediate send. Use list_sms_dynamic_fields to see all available dynamic fields (e.g. {First name}) before composing text. Use search_sms_templates to find available template IDs. Use search_contacts or get_contact to find contact IDs. Use search_lists to find list IDs. Use list_contact_segments to find segment IDs.

preview_sms

Remove one or more contacts (by their IDs) from a contact list. Use search_contacts to find contact IDs and search_lists to find the list ID before calling this tool. Contact IDs that do not belong to the current user or are not in the list are silently ignored — the call succeeds regardless. Returns the list ID, name, and updated contacts count as confirmation.

remove_contacts_from_list

Remove one or more tags (by their IDs) from one or more contacts (by their IDs). Use search_tags to find tag IDs and search_contacts to find contact IDs before calling this tool. Tag IDs or contact IDs that do not belong to the current user, or tag-contact pairs that are not currently applied, are silently ignored. Returns a success message when the operation completes.

remove_tags_from_contacts

Find existing contacts in the user's Textmagic account by name, phone, email, listId, tagIds, countries, or segmentId. Returns 10 per page. Use to resolve a contact reference or get an ID before send_sms / add_contacts_to_list. Not for creating (create_contact) or full export. Requires at least one of: query, listId, tagIds, countries, segmentId. segmentId filters by a saved contact segment (use list_contact_segments to find IDs); it CANNOT be combined with listId, tagIds, or countries, but can be combined with query. Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of matching contacts across all pages.

search_contacts

Find contact lists (groups) in the user's Textmagic account. Returns up to 10 lists per page with id, name and contacts count. Without a query, returns all lists ordered by name. With a query, filters by name using a partial, case-insensitive match. Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of matching lists across all pages.

search_lists

Find SMS chats in the user's Textmagic account. Returns 10 per page. Optionally filter by a search query (matched against contact name or phone number) and/or unread status. Use to look up chat IDs before replying or to surface unread conversations. Returns only SMS chats — not WhatsApp, Facebook Messenger, Instagram, or live chats. Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of matching chats across all pages.

search_sms_chats

Find SMS message templates in the user's Textmagic account. Returns up to 10 templates per page with id, name, and content. Without a query, returns all templates ordered by name. With a query, performs a case-insensitive partial match across both template name and content. Returns an empty list when no templates match — not an error. Page only when pagination.hasNextPage is true. pagination.totalCount is the total number of matching templates across all pages.

search_sms_templates

Find tags in the user's Textmagic account. Returns all matching tags with id and name. Without a query, returns all tags (max 100 results). With a query, filters by name using a partial, case-insensitive match. pagination.totalCount is the total number of matching tags; if it exceeds the returned count, refine the query to narrow results. Use to resolve tag references or get IDs before add_tags_to_contacts.

search_tags

Send an SMS message to one or more recipients using a previously created preview. IMPORTANT — this is a DESTRUCTIVE, IRREVERSIBLE operation: - It delivers real SMS messages to live recipients. - It uses up the account balance. - There is no undo. Always call preview_sms first and show the user the recipient count and message text. Only call this tool after the user has explicitly confirmed they want to proceed with the send. The `cost` is in the account currency — see the `currency` field. If the preview was created with a scheduleToken (a delayed or recurring send), this tool confirms the schedule instead of sending immediately: the response reports `scheduled: true` with the rrule and upcoming send datetimes. A confirmed schedule is ongoing — every future occurrence sends automatically until the schedule ends or is cancelled. The `previewId` returned by preview_sms is valid for 30 minutes. If the underlying conditions (recipients, message) have changed since the preview was created, the send is rejected automatically to protect against sending with stale data. US and Canadian recipients require a registered sender (a verified 10DLC campaign for the US, a verified toll-free number for either). When the account has none, a send whose recipients are all in the US/Canada is rejected with a link to the sender settings, and a send that only partly targets them succeeds but returns a `warning` field — relay that warning to the user verbatim. Rate limits: - Maximum 1 send per minute per account. - Maximum 10 000 recipients per day per account.

send_sms

Updates an existing contact in the Textmagic address book. Use when the user wants to change a contact's phone, email, first name, last name, or company name. Requires the contact id (integer). Only the fields you pass are changed — omitted fields are left as-is. Do NOT use to create a new contact (use create_contact) or to add the contact to a list (use add_contacts_to_list). Returns the updated contact's id and core fields.

update_contact