# Sinch MCP

> Sinch provides your AI agent with full control over SMS communication at scale. Use it to send text messages (SMS) to single contacts or large groups. You can manage contact lists, check delivery reports for failed/pending messages, and update entire message batches directly via natural language prompts.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** sms-api, bulk-messaging, delivery-tracking, voice-api, customer-engagement, notifications

## Description

You're connecting your AI agent to **Sinch**, a heavy-duty platform built for handling SMS at scale. This setup gives you full control over every part of an SMS campaign—from building contact lists to managing what happens after you hit send. You don't just send texts; you manage the whole damn process.

### Sending Texts (Send Text Messages)

To blast out a message, you use the `send_sms` tool. It handles sending text messages (SMS) to one or multiple people using international formatting. Whether you need to hit up single contacts or send out a burst of texts, this tool gets it done.

### Managing Contacts (Manage Contact Groups)

You gotta organize your numbers first. You can use `create_sms_group` to build and save brand new groups of phone numbers specifically for campaigns. If you need the rundown on an existing group, run `get_group_details`; that'll tell you exactly how many members are in it. And if a campaign is done or the list got trashed, you can permanently wipe out an old contact group using `delete_sms_group`. To see what groups you’ve already set up, just call `list_sms_groups`.

### Tracking Deliveries (Track Delivery Status)

When it comes to knowing if your message actually landed, the `get_delivery_report` tool is key. It pulls the full delivery report for a batch, letting you see the total number of people targeted, how many delivered, which ones are still pending, and exactly where the failures happened. You won't be guessing about your reach with this.

### Controlling Message Batches (Control Message Batches)

The `list_sms_batches` tool generates an inventory of all recent SMS batches that have been created or processed. If you need deep facts on a specific batch, use `get_batch_details`; it'll show you the status and parameters used for that run. You can also modify what’s in an already-existing campaign using `update_sms_batch`. And if something goes sideways before delivery, you can stop the whole thing dead with `cancel_sms_batch`. Keep in mind, though: this action is irreversible.

### Getting Your Overview (List Contacts)

To keep everything straight, you've got two listing tools. You can call `list_sms_groups` to get an inventory of every contact group defined. For a history check on campaigns, run `list_sms_batches` to see all recently processed batches.

## Tools

### cancel_sms_batch
Stops an entire SMS batch that hasn't been delivered yet. Note: this action cannot be undone.

### create_sms_group
Builds and stores a new, dedicated group of phone numbers for campaign use.

### delete_sms_group
Permanently removes an existing contact group. This action cannot be undone.

### get_batch_details
Fetches detailed information about a specific SMS batch, including its status and parameters.

### get_delivery_report
Retrieves the full delivery report for a batch, showing total recipients, delivered count, pending messages, and failures.

### get_group_details
Reads specific information about an existing contact group, including its membership count.

### list_sms_batches
Generates a list of recent SMS batches that have been created or processed.

### list_sms_groups
Returns an inventory of all contact groups currently defined in the system.

### send_sms
Sends one or more text messages (SMS) to specified international phone numbers.

### update_sms_batch
Modifies the parameters of an SMS batch that already exists in the system.

## Prompt Examples

**Prompt:** 
```
Send an SMS to +1234567890 saying 'Your order has been shipped!'
```

**Response:** 
```
SMS sent successfully.
- Batch ID: batch-7k2m
- Recipient: +1234567890
- Message: 'Your order has been shipped!'
- Status: queued for delivery
```

**Prompt:** 
```
Get the delivery report for batch 9876.
```

**Response:** 
```
Delivery report for batch 9876:
- Total recipients: 12,000
- Delivered: 11,842 (98.7%)
- Pending: 112
- Failed: 46
- Sender ID: 'Vinkius'
Would you like details on the failed deliveries?
```

## Capabilities

### Send Text Messages
Sends a text message (SMS) to one or multiple recipients using the international format.

### Manage Contact Groups
Creates, reads details for, and deletes groups of phone numbers used for targeted messaging.

### Track Delivery Status
Retrieves delivery reports for SMS batches to see the total count, delivered percentage, pending messages, and failures.

### Control Message Batches
Lists recent batches, retrieves specific batch details, or updates parameters on an existing batch.

### List Contacts
Retrieves a list of all defined contact groups and recently sent SMS batches for review.

## Use Cases

### Handling an emergency product recall message.
The marketing lead needs to notify 50 key clients immediately. They ask their agent: 'First, list all contact groups.' The agent uses `list_sms_groups` to find the VIP group ID. Then, it calls `send_sms` with the critical alert message and gets immediate confirmation of the batch initiation.

### Verifying a large mailing's success rate.
An operations team sends 20,000 messages. Hours later, they need to know how many failed due to bad numbers. They prompt their agent: 'Get the delivery report for batch 123.' The agent uses `get_delivery_report` and provides a breakdown of failures vs. successes instantly.

### Adjusting an ongoing marketing campaign.
A campaign targeting new users needs a slight change in message content mid-day. Instead of restarting, the manager tells their agent: 'Update batch 456 with this new text.' The agent uses `update_sms_batch` to modify parameters on the existing batch without downtime.

### Cleaning up obsolete contact lists.
The company acquired a client list but some groups are outdated. A developer instructs their AI agent: 'Review all current groups and delete group 7.' The agent runs `list_sms_groups` first, verifies the name, then uses `delete_sms_group`, making cleanup traceable.

## Benefits

- Audit failed deliveries instantly. Instead of waiting for manual reports, use `get_delivery_report` to get precise metrics on delivered vs. failed messages after any campaign run.
- Manage recipients like a pro. Use `create_sms_group` and `list_sms_groups` to keep your contact lists clean and segmented before running campaigns, ensuring you only target active numbers.
- Control the message lifecycle. If a batch needs adjusting or cancellation, use `get_batch_details` and `update_sms_batch` to intervene mid-process without manual API calls.
- Process high volumes reliably. The `send_sms` tool handles multiple international phone numbers in one go, making bulk outreach simple for your agent.
- Simplify list maintenance. Instead of manually checking which groups exist, run `list_sms_groups` to get a complete inventory and plan your next campaign.

## How It Works

The bottom line is you get a full command-line interface for SMS marketing, letting your AI client manage campaigns without touching a dashboard.

1. First, provide the Sinch API credentials (Service Plan ID and API Token) to your AI client.
2. Next, instruct your agent on the workflow—for example, 'List all contact groups,' or 'Send a reminder SMS to group X.'
3. The agent uses the exposed tools (`list_sms_groups`, `send_sms`, etc.) to execute the commands and returns structured data about the results (e.g., delivery status, batch ID).

## Frequently Asked Questions

**How do I check if a group exists using Sinch MCP Server?**
You run `list_sms_groups` to view all existing groups. If the group you need isn't listed, you must use `create_sms_group` first.

**Can I cancel a message send using Sinch MCP Server?**
Yes, if the batch hasn't left the system yet, you can call `cancel_sms_batch`. This is useful for catching mistakes before they cost money or frustrate customers.

**What tool do I use to send messages with Sinch MCP Server?**
You use the `send_sms` tool. Remember to provide phone numbers in international format (e.g., +1234567890) for it to work.

**What is the difference between `get_batch_details` and `get_delivery_report` using Sinch MCP Server?**
`get_batch_details` gives you metadata about the batch itself (like its parameters or status). `get_delivery_report` provides the outcome—the actual delivery counts, failures, and success percentage.

**What credentials do I need to successfully use the `send_sms` tool?**
You must provide your Sinch Service Plan ID and API Token. The server uses these keys for authentication, so you'll set them up once in your AI client connection. You won't have to worry about manual auth steps again.

**When using the `send_sms` tool, what phone number formatting is required?**
Numbers must be in international format (e.g., +1234567890). You can send texts to multiple recipients; just list all the numbers you want in the 'to' field. The API handles sending them out.

**How do I change parameters for a batch using `update_sms_batch`?**
The tool lets you adjust settings on an existing, pending SMS batch. You must provide the Batch ID and define exactly what parameters need updating. This is useful if campaign details change before they are sent out.

**What specific data points does `list_sms_batches` provide?**
This tool returns a list of recent SMS batches, including the Batch ID, when it was created, and its current status. Your agent uses this data to select which batch needs further monitoring or action.

**Can it accidentally affect my entire Sinch account?**
No. The integration only supports sending SMS, managing batches, and handling contact groups. It cannot modify billing, account settings, or access other Sinch services.

**How does authentication work?**
You provide your Service Plan ID and API Token. The integration generates a Bearer token header automatically for each request — no OAuth setup required.

**What is a batch in Sinch?**
A batch is a single SMS send operation that can target one or many recipients. Each batch has a unique ID and can be tracked, updated, or cancelled before delivery.