# MagicBell MCP > MagicBell manages notifications and broadcasts right from your AI client. Use the `list_broadcasts` tool to see history across Email, SMS, and Push channels. You can use `get_broadcast` to check a specific message's delivery status or `create_broadcast` to trigger an alert immediately without touching a dashboard. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** notifications, multi-channel, push-alerts, broadcast-management, inbox-management, event-triggers ## Description MagicBell manages all your alerts—the whole shebang, across every channel you use. You connect your AI client directly, and it gives you total control over broadcasting messages using natural language commands. This isn't some dashboard you gotta mess with; your agent runs these tools right from your code editor. You want to know what happened last week? Use the `list_broadcasts` tool. It pulls up a paginated list of every single broadcast that’s gone out for your project. You get titles and unique IDs, giving you a full audit trail of all your communication efforts. That's how you track everything. Need to dig into one specific message? Just grab the UUID and run `get_broadcast`. This tool fetches the complete status and all the metadata for that single broadcast. It tells you if it was 'processed,' what the full content was, and exactly how many people received it across all channels. You're getting the deep dive here. When it’s time to send a message—and you gotta send one—you call `create_broadcast`. This tool handles sending a brand new multi-channel alert instantly. You specify the title, the body text, and any necessary filters, and MagicBell triggers the alerts across email, SMS, or push channels automatically. It doesn't matter if you want it to hit all three; the server manages that routing for ya. When a broadcast goes out using `create_broadcast`, the system is smart about reporting back. The server reports which specific channels were actually used—like Email or Web Push—and gives you a count of how many recipients got hit on each one. This means you know exactly what happened with every single message sent. Think about it: You don't have to jump through hoops in some web portal just to send an alert or check if Uncle Joe actually got that push notification. Your AI client handles the whole cycle. First, you use `list_broadcasts` to get a quick overview of all previous sends; you see the titles and unique IDs pop up right away. If you spot a UUID for something you need details on, you hit `get_broadcast`. That gives you the full picture: the content, the status confirmation, and the exact recipient count. It’s immediate verification. You're checking the metadata so you know it wasn't just *sent*; you know it was processed. And when you need to send a message, that's where `create_broadcast` shines. You feed it the title and body text—the stuff people gotta read—and tell it what filters to use. It then fires off that alert across email, SMS, or push channels simultaneously. The system takes your single command and executes complex multi-channel routing. You get confirmation on which specific channel was used for each recipient group, and how many folks got the message. It's airtight. This whole setup means you keep all your communication control right inside your development environment. You don't gotta break flow switching between tools. Your agent calls `list_broadcasts` to see history; it calls `get_broadcast` when it needs confirmation on a specific alert ID; and it uses `create_broadcast` the second an alert is necessary. It’s seamless, baby. ## Tools ### create_broadcast Sends a brand new multi-channel broadcast alert with specified title, content, and filters. ### get_broadcast Fetches the complete status and metadata for one specific broadcast using its unique ID (UUID). ### list_broadcasts Retrieves a list of all broadcasts that have been sent in your project, providing an audit trail. ## Prompt Examples **Prompt:** ``` List all recent broadcasts in my MagicBell project. ``` **Response:** ``` I've retrieved the broadcasts for your project. You have 3 recent entries: 'Welcome Campaign' (ID: 8a2...), 'System Alert' (ID: 4f1...), and 'Weekly Digest' (ID: 9c2...). Which one would you like to inspect? ``` **Prompt:** ``` Show me the details and status for broadcast ID 550e8400-e29b-41d4-a716-446655440000. ``` **Response:** ``` Inspecting broadcast 550e8400... The status is 'processed'. It was sent with the title 'Maintenance Notice' and reached 1,240 recipients across Email and Web Push channels. ``` **Prompt:** ``` Create a new broadcast titled 'Flash Sale' with content 'Get 50% off today only!' for all recipients. ``` **Response:** ``` I've successfully created the 'Flash Sale' broadcast. It is now being processed and triggered for your recipient list. You can track its progress using the generated ID: 771b92... ``` ## Capabilities ### List all historical broadcasts Run `list_broadcasts` to get a paginated list of every broadcast sent, showing titles and unique IDs. ### Retrieve specific broadcast details Use `get_broadcast` with a UUID to pull the full content, status (e.g., 'processed'), and recipient counts for one message. ### Send new multi-channel alerts `create_broadcast` sends an alert using specified titles, bodies, and filters across email, SMS, or push channels. ### Check delivery status per channel The server reports which specific channels (Email, Web Push) were used for a broadcast and how many recipients received it. ## Use Cases ### A critical system alert needs to go out immediately. The SRE notices a service degradation. Instead of opening the internal dashboard and manually triggering the announcement flow, they prompt their agent: 'Run `create_broadcast` for an outage notice.' The tool executes, sending the message across all necessary channels (SMS and Push) instantly. ### Need to confirm if a quarterly update reached everyone. The Product Manager needs to verify who saw the 'Q3 Feature Rollout' announcement. They prompt their agent: 'Run `get_broadcast` for UUID 4f1...' The server returns the exact status, showing how many people received it across different channels. ### Auditing a campaign that ran last week. The Support Lead needs to prove when and what was communicated during an incident. They run `list_broadcasts`. The agent pulls the full history, allowing them to quickly confirm the 'System Alert' went out exactly at 2:00 PM. ### A small feature requires a targeted announcement. The team wants to announce a change only to internal users. They use `create_broadcast`, setting filters that restrict the broadcast payload to 'internal' recipients, ensuring external customers don't see it. ## Benefits - See the full history of all communications by running `list_broadcasts`. You get an immediate audit trail without clicking through multiple dashboards or reports. - Check a specific message's delivery status instantly. Use `get_broadcast` to confirm if 1,240 people actually got the 'Maintenance Notice' across Email and Web Push. - Trigger emergency alerts on the fly. Calling `create_broadcast` lets you send an urgent announcement immediately when something breaks, no manual deployment required. - Control specific channels for better targeting. When calling `create_broadcast`, you can set overrides so a message only goes out via SMS, even if email is primary. - Keep communication logs centralized. The server aggregates status and metadata from multiple channels (Email, SMS, Push) into one accessible API endpoint. ## How It Works The bottom line is, your AI client uses these tools to talk directly to MagicBell's API, letting you manage complex alerts without writing any code outside of your prompt. 1. First, subscribe to the MagicBell server and enter your project JWT into your AI client. 2. Then, tell your agent what you need. For example: 'List all broadcasts from last week.' 3. The agent executes `list_broadcasts` (or another tool) and returns the data—the full message history is ready for you to read. ## Frequently Asked Questions **How do I check if an old broadcast was successful using get_broadcast?** You pass the unique UUID to `get_broadcast`. The tool returns the status, telling you if it was 'processed' and how many recipients across all channels received it. **What is the difference between list_broadcasts and get_broadcast?** `list_broadcasts` gives you a summary view of everything sent (like an index). `get_broadcast` requires a specific UUID to fetch the full, detailed status for just that one message. **Can create_broadcast send messages only via SMS?** Yes. When calling `create_broadcast`, you can define channel-specific overrides and filters. You control exactly which channels (Email, SMS) receive the alert for that specific payload. **Does MagicBell track multiple broadcast types?** The server logs all broadcasts passing through it. By using `list_broadcasts`, you can see a comprehensive history of different campaign types or alerts sent via your project. **What authentication key do I need to provide when running list_broadcasts?** You must use your MagicBell Project JWT. This token authenticates your agent and grants it permission to view the specific broadcast history for that project. You don't send generic credentials; you send the unique project key. **If a broadcast fails, what details can I get using get_broadcast?** The metadata includes detailed failure status and an error code. This lets you know if the failure was due to bad content, invalid recipient lists, or a channel-specific issue (like an expired API key for SMS). **Are there rate limits when I use create_broadcast?** Yes, MagicBell enforces rate limits tied to your subscription tier. If you hit the limit, the server sends a 429 error code, telling your agent exactly how long to wait before retrying the broadcast. **How do I ensure only specific groups receive messages with create_broadcast?** You specify recipient filters in the payload. You can target users by segment, ID list, or even restrict delivery based on channel type (e.g., email-only). This prevents sending announcements to unintended audiences. **Can I send a notification to specific users or groups?** Yes! When using the `create_broadcast` tool, you can provide an array of user IDs or emails in the `recipients` field to target specific individuals or segments. **How do I check if a broadcast has been successfully processed?** You can use the `get_broadcast` tool with the unique broadcast ID. It will return the current processing status and metadata for that specific notification event. **Is it possible to customize the message content for different channels like Email or SMS?** Absolutely. The `create_broadcast` tool includes an `overrides` parameter where you can specify different content or templates for specific channels (email, sms, push).