🏢 Maata Business Messaging API
Send messages from your software (school, bank, hospital, office, shop) to customers in the Maata app. Version 1.
mk_test_…) and try it on your own phone. 3) After verification, create a live key (mk_live_…). Keep keys on your server only — never in an app or web page.Send a message
curl -X POST https://maataapp.com/v1/messages \
-H "Authorization: Bearer mk_live_xxx" -H "Content-Type: application/json" \
-d '{"to":"9876543210","template":"fee_reminder","variables":{"student_name":"Ravi","amount":"₹2,500","due_date":"20 Oct"},"idempotency_key":"fee-2026-10-ravi"}'
Response 202: {"id":"msg_…","status":"accepted",…}. Optional: "send_at":"2026-10-20T09:00:00+05:30" to schedule. Free text ("text":"…" instead of a template) is allowed only within 24 hours after the customer replied.
Message states
accepted / queued → sent → delivered (reached the phone) → read, or failed. Check with GET /v1/messages/{id}.
Other endpoints
| GET /v1/templates | Your templates, status and variables. |
|---|---|
| GET /v1/usage | Today's count and limits. |
| GET /v1/customers/{phone} | Is the person on Maata, and can you message them? |
Consent rules
- Transactional (fees, bills, appointments, orders): the customer has a relationship with you or opted in.
- Marketing: only customers who chose "All messages" for you.
- Customers can choose All / Important only / None, reply STOP, or report you. Share your opt-in link:
https://maataapp.com/?optin=YOUR_BUSINESS_ID - Templates must not contain OTPs, passwords, PINs or card numbers.
Webhooks
Add an https address in the dashboard. Maata POSTs JSON events: message.delivered, message.read, message.received (customer reply), customer.opted_in, customer.opted_out, test.ping. Failed deliveries are retried (10 s, 1 min, 5 min, 30 min, 2 h).
Check the signature: header X-Maata-Signature: t=TIMESTAMP,v1=HEX where HEX = HMAC-SHA256(your whsec_… secret, TIMESTAMP + "." + raw body). Reject if older than 5 minutes.
// Node.js
const [t, v1] = sig.split(',').map(s => s.split('=')[1]);
const ok = crypto.createHmac('sha256', SECRET).update(t + '.' + rawBody).digest('hex') === v1;
Errors
| not_on_maata | This number is not on Maata. |
|---|---|
| opted_out | The customer turned off messages from you. |
| no_consent | The customer has not opted in. Share your opt-in link or QR first. |
| no_marketing_consent | Marketing needs the customer to choose "All messages" for your business. |
| not_verified | Your business is not verified yet. Use a test key (mk_test_) until Maata verifies you. |
| test_only_team | Test keys can send only to your own team (owner and staff). |
| rate_limited | Too many messages. Slow down. |
| daily_limit | Daily message limit reached. |
| bad_template | Template not found or not approved. |
| missing_variable | A template variable is missing. |
| window_closed | Free text is allowed only within 24 hours after the customer messaged you. Use a template. |
| suspended | Messaging for this business is suspended. |
Limits
Test keys: 30/min, 200/day, only to your own team. Live keys: 300/min, 20000/day (can be raised).