canonical: https://jentic.com/apis/roezan.com/roezan

# Roezan Integrations API

The Roezan Integrations API sends SMS and MMS messages from a Roezan account and keeps its contact lists, tags, and custom fields in sync with other services. It creates or updates contacts by phone number, subscribes and unsubscribes them from lists, and adds or removes tags. Broadcasts follow a two-step flow: create a draft against one or more lists with a recipient count and credit estimate, send a test to one phone, then schedule it or send it now, and poll its status and delivery counters afterwards. Webhook subscriptions deliver events such as message status to a URL of your choice.

## For AI agents

Send SMS and MMS through a Roezan account, manage contacts, lists, and tags by phone number, and draft, preview, schedule, and track SMS broadcasts.

## Scope

Does not place voice calls, send email campaigns, or provision new phone numbers. Use for SMS and MMS messaging, contact lists, and broadcasts on a Roezan account only.

## Capabilities

- Send an SMS or MMS to a phone number, with up to 10 media links, from a chosen sender number
- Create or update a contact by phone with first name, last name, email, lists, and tags
- Subscribe a contact to a list or unsubscribe them, using list IDs from the lists call
- Draft a broadcast for one or more list_ids and get the expected recipient count and credit estimate
- Send a broadcast preview to one phone, then schedule it, send it now, or cancel a pending send
- Read a contact's message history and a broadcast's recipients with cursor pagination
- Subscribe a hookUrl to Roezan webhook events and delete subscriptions you no longer need

## Use cases

### AI agent that texts customers from your Roezan number

An AI agent handling follow-ups can send a text from the business's own Roezan number instead of a separate SMS gateway. Through Jentic the agent searches for 'send an SMS', loads the Roezan send-message operation with its input schema, and posts the phone, message, and sender with the API key added at call time. Because the contact and its history live in Roezan, the conversation stays in the same inbox the team already uses.

Example prompt: GET `/api/integrations/senders` to pick a sender, then POST `/api/integrations/message/send` with phone, countryCode, from, and the follow-up message

### Syncing leads into lists and tags

When a form or CRM captures a lead, an integration creates or updates the Roezan contact by phone and subscribes it to the right list. Tags can be added or removed by tag ID, and custom fields defined on the account can be set on the contact. List and tag IDs come from the lists and tags calls, so the integration never hard-codes them.

Example prompt: GET `/api/integrations/lists` to find the 'New leads' list ID, then POST `/api/integrations/lists/subscribe` with that list and the lead's phone

### Scheduled SMS broadcasts with a safety check

A broadcast starts as a draft that names the lists, message, and optional schedule, and the response returns the expected recipient count and a credit estimate before anything is sent. A preview call sends one test message to a real handset. Scheduling moves the draft to pending, a pending broadcast can be cancelled back to a draft, and the status call reports delivery counters after the send.

Example prompt: POST `/api/integrations/broadcasts` with name, list_ids, and message, POST `/api/integrations/broadcasts/{id}/preview` to one phone, then POST `/api/integrations/broadcasts/{id}/schedule` with scheduled_time and scheduled_timezone

### Delivery and reply events to your own service

A webhook subscription is one event and URL pair, so a service subscribes once per event it wants. Subscriptions can be filtered by lists and tags, include broadcasts, and carry a signing secret for verifying deliveries. Listing subscriptions shows those created through the API, the Roezan dashboard, or connected apps such as Zapier.

Example prompt: POST `/api/integrations/hooks` with event 'message.status', a hookUrl, and a signingSecret, then GET `/api/integrations/hooks` to confirm it is listed

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/integrations/message/send` | Send an SMS or MMS |
| POST | `/api/integrations/contacts` | Create or update a contact |
| POST | `/api/integrations/lists/subscribe` | Subscribe a contact to a list |
| POST | `/api/integrations/broadcasts` | Create a draft broadcast |
| POST | `/api/integrations/broadcasts/{id}/schedule` | Schedule or send a broadcast |
| GET | `/api/integrations/broadcasts/{id}` | Get broadcast status and delivery stats |
| GET | `/api/integrations/contacts/{id}/messages` | Get a contact's message history |
| POST | `/api/integrations/hooks` | Subscribe to a webhook event |

## Key resources

- **Messages** — SMS and MMS sends and per-contact message history
- **Contacts** — Contacts keyed by phone or email, with lists, tags, and custom fields
- **Broadcasts** — Draft, preview, schedule, cancel, and status of list-wide SMS sends
- **Webhook subscriptions** — Event and URL pairs that deliver Roezan events to your service

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 89 / 100
  - Developer Experience & Jentic Compatibility: 77 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 84 / 100
- **View full report:** https://jentic.com/apis/roezan.com/roezan/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Roezan by hand means sending the account key in the x-api-key header, looking up list, tag, and sender IDs before you can act, and following the draft, preview, and schedule sequence for broadcasts. Through Jentic you install once, import Roezan from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Roezan carries the phone number and list inside the request body for sends and subscriptions, so rules bound which operations your agent may call, not which contact it reaches. Broadcast calls put the broadcast id in the URL path, so a rule can pin your agent to one broadcast for preview and status. You choose the operations it may call, so sending ones like message send or broadcast scheduling are not included unless you add them.
- **Credential handling:** Your Roezan API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send an SMS' or 'schedule a text broadcast', and Jentic returns the matching Roezan operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Textmagic API** — Business SMS sending, contact lists, and bulk campaigns
- **EZ Texting API** — SMS marketing platform with contacts, groups, and scheduled campaigns
- **Attentive API V2** — SMS and email marketing for e-commerce brands with subscriber events
- **Klaviyo API** — Email marketing and customer profiles that can feed SMS lists

## FAQ

### What authentication does the Roezan Integrations API use?

Per its OpenAPI spec, the Roezan Integrations API authenticates with your account API key sent in the `x-api-key` request header. Through Jentic the key is held by your own instance and injected at call time, so the agent never sees it.

### Can I schedule an SMS broadcast with the Roezan Integrations API?

Yes. POST `/api/integrations/broadcasts` creates a draft for one or more list_ids and returns the expected recipient count and a credit estimate. POST `/api/integrations/broadcasts/{id}/schedule` then schedules it with scheduled_time and scheduled_timezone, or sends it now with send_now, and GET `/api/integrations/broadcasts/{id}` reports its status and delivery counters.

### What are the rate limits for the Roezan Integrations API?

The OpenAPI spec states per-credential limits on some operations, in addition to a global integrations limit it does not quantify: 5 requests/second for the message-history and broadcast-recipient reads, and 1 request/second for creating, previewing, scheduling, and cancelling broadcasts. Exceeding a limit returns 429 with RateLimit headers. Contact support@roezan.com for the current global limit.

### Is there a Roezan MCP server?

You do not need an MCP server to give your agent Roezan. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the messaging, contact, and broadcast operations it needs on demand without loading another server's tool definitions into its context.

### How do I send an SMS through Jentic with the Roezan Integrations API?

Search Jentic for 'send an SMS', load the POST `/api/integrations/message/send` operation, and execute it with phone and message, plus from to choose one of the numbers returned by GET `/api/integrations/senders.` To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Roezan Integrations API?

Yes. For a list-hygiene agent, write a rule that allows only POST `/api/integrations/contacts` and POST `/api/integrations/lists/subscribe`, so it can add and update contacts and subscribe them to lists but cannot send a message, schedule a broadcast, or delete webhooks. Every call it makes is logged.

### Can I send MMS with images through the Roezan Integrations API?

Yes. POST `/api/integrations/message/send` accepts media links alongside the message body. The spec allows a maximum of 10 media links per message and a maximum message size of 5MB.
