MeTicket SMS Gateway API
Send SMS to any Malawian mobile number through one REST API. The gateway picks Airtel or TNM from the number prefix, charges your MWK balance per segment, and reports delivery back to you.
- Base URL
- https://smpp.meticketmw.com
- Auth
- ApiKey header
- Format
- JSON over HTTPS
- Currency
- MWK
- SMPP
- v3.4 · port 2775
How an SMS gateway works
Your application cannot put a text message on a phone by itself. Only the mobile networks can. Airtel and TNM each run an SMSC (Short Message Service Centre), the system that delivers texts to handsets. Connecting to an SMSC directly takes a contract with the network, approved credentials and a binary protocol called SMPP, and you would need all of that twice: once for Airtel and once for TNM.
The MeTicket gateway already holds those connections. You send one HTTPS request with JSON, and the gateway checks it, charges it, picks the right network and passes it on over SMPP. When the network reports back, the gateway tells you.
The life of one message
You send a request
Your server POSTs the number, your Sender ID and the text to /api/messaging/send.
The gateway checks it
It confirms your API key, checks that your Sender ID is approved, and checks that your balance covers every segment. If any check fails, nothing is sent and you get a 401, 403 or 402.
It picks the network
The number is converted to
265…form and its prefix decides the network: 099 goes to Airtel, 088 goes to TNM. See Numbers & routing.You get a messageId straight away
The message is queued and you get a reply within milliseconds, with status
SUBMITTED. Your code does not wait for the network.The network takes it
The gateway sends the message to Airtel or TNM over SMPP. Once the network accepts it, the status becomes
ENROUTE.The phone receives it
This usually takes a few seconds. If the phone is off or out of coverage, the network keeps trying for a while.
The network reports back
The network sends a delivery receipt (DLR). The status becomes
DELIVRD, orUNDELIVif delivery failed. Prepaid accounts get an UNDELIV message refunded.You find out
If you set up a webhook, the gateway POSTs the result to your server. Otherwise, read it from the status endpoint.
What you see, and when
| When | Status | How you know |
|---|---|---|
| Instantly | SUBMITTED | Send response |
| ~1 second | ENROUTE | Status endpoint |
| Seconds to hours | DELIVRD | Webhook or status |
| Seconds to hours | UNDELIV | Webhook or status |
A successful send response means the gateway accepted your message. Only DELIVRD means it reached the phone.
Terms you will see
- SMSC
- The network's message centre. Airtel and TNM each run one, and it delivers texts to phones.
- SMPP
- The protocol gateways use to talk to an SMSC. You only need it for very high volume; see SMPP connection.
- Sender ID
- The name a recipient sees instead of a number, such as MYBANK. The networks must approve it first.
- Segment
- One SMS-sized piece of a message, up to 160 characters. Longer texts are split, and each segment is charged.
- DLR
- Delivery receipt. The network's report of whether a message reached the phone.
- MO
- Mobile originated. A text a person sends to your Sender ID, such as a STOP reply.
Quickstart
Get your credentials
MeTicket issues your API key and registers your Sender ID (the name on the handset, such as
MYBANK) with both carriers. Email sms@meticketmw.com to start.Check the key works
Call GET /api/auth/whoami. You get your account, billing type, balance and price per SMS back.
Send your first SMS
POST to /api/messaging/send with
to,fromandmessage. Save themessageIdfrom the response and track it with the status endpoint or a webhook.
Authentication
Every request carries your API key in a header. There is no login step and no token exchange. Two header forms are accepted:
| Header | Notes |
|---|---|
Authorization: ApiKey <key> | Preferred |
X-API-Key: <key> | Alternative |
Use whoami to confirm the key and read your account settings.
Keep the key on your server. Never put it in browser JavaScript or a mobile app. If it leaks, ask MeTicket to rotate it. Always call the API over HTTPS.
Numbers & carrier routing
Send numbers in E.164 form (+265991234567). Local forms are converted for you: 0991234567 becomes 265991234567. The gateway reads the first digits after 265 and picks the carrier. The longest matching prefix wins.
| Carrier | Prefixes | Example |
|---|---|---|
| Airtel | 265 99 · 98 · 97 · 91 | +265991234567 |
| TNM | 265 88 · 85 · 84 · 83 | +265881234567 |
| Fallback | Any other prefix | Routed via Airtel |
To force a carrier, pass "carrier": "airtel" or "tnm" in the send request.
Route a number
- Normalised
- —
- Matched prefix
- —
- Carrier
- —
Uses the same prefix rules as the gateway's default configuration.
Message statuses
A message moves through these states. Read them from the status endpoint or receive them through a DLR webhook.
| Status | Meaning | What to do |
|---|---|---|
| SUBMITTED | Accepted by the gateway and queued for the carrier. | Wait. |
| ENROUTE | Handed to the Airtel or TNM SMSC. Waiting for the handset. | Wait. Phones that are off can take hours. |
| DELIVRD | The carrier confirmed delivery to the handset. | Final. |
| UNDELIV | The carrier could not deliver. Prepaid accounts are refunded automatically. | Final. Check the number. |
| FAILED | Not sent, because of balance or a carrier error. | Final. Check balance, then retry. |
| CANCELLED | Stopped before it reached the carrier. | Final. |
Send SMS
Sends one message to one or more numbers. Each number is routed, charged and queued on its own, and gets its own messageId.
Body
| Field | Type | Description | |
|---|---|---|---|
| to | string | array | Required | One number, a comma-separated string, or a JSON array. E.164 preferred. |
| from | string | Required | Your Sender ID. It must be ACTIVE on your account. |
| message | string | Required | Message text. Up to 160 characters is 1 segment; longer text is billed in 153-character segments. |
| carrier | string | Optional | airtel or tnm to skip automatic routing. |
Response
| Field | Description |
|---|---|
| Message | Summary, such as Sent to 3/3 contacts. |
| Recipients[].status | Success or Throttled. A throttled number was not sent and has no messageId; send it again later. |
| Recipients[].statusCode | 101 on success. |
| Recipients[].messageId | UUID for status checks, DLRs and support requests. Store it. |
| Recipients[].carrier | airtel or tnm. |
| Recipients[].cost | Amount charged, such as MWK 3.50. |
A 200 means the request was accepted, not that every number was sent. Read status on each recipient.
HTTP sends go out as GSM-7. Keep to standard Latin characters. Emoji and non-Latin scripts may not display correctly on the handset.
Bulk send
The same endpoint takes many numbers. Pass an array or a comma-separated string in to. Numbers on different carriers can be mixed in one call.
- The gateway checks your balance for the whole batch first. If it is short, nothing is sent and you get
402. - The per-second limit applies to each number. Numbers over the limit come back as
Throttled. - Send batches of 1,000 numbers or fewer.
Message status
Returns the current status of one message, with the time it was sent and the time it was delivered.
| Path | Description |
|---|---|
| messageId | The UUID from the send response. |
deliveredAt is null until a delivery receipt arrives. Returns 404 if the message is not on your account.
Delivery receipts
Returns the raw receipts the carrier sent for a message, newest first. Use it when a status looks wrong. The err code and rawPdu are what MeTicket support will ask for.
List messages
Lists your messages, newest first.
| Query | Default | Description |
|---|---|---|
| limit | 50 | Page size. Maximum 500. |
| offset | 0 | Rows to skip. |
| status | — | Filter, such as DELIVRD or UNDELIV. |
Get a message
Returns the full stored record for one message: text, sender, segments, cost and timestamps.
Carrier status
Shows whether the gateway is currently connected to Airtel and TNM. If a carrier is not ready, messages for it stay queued until it reconnects.
Usage summary
Message counts and spend for a date range, with your current balance and rate. from and to are optional here (YYYY-MM-DD).
Sender IDs
Lists the Sender IDs on your account. Only those with status: "ACTIVE" work in the from field.
Sender ID formats
| Type | Format | Example |
|---|---|---|
| Alphanumeric | 3–11 letters and digits, at least one letter | MYBANK |
| Numeric | 5–15 digits | 265999 |
| Short code | 3–6 digits | 1234 |
Email MeTicket with the ID you want, your registered company name, its use (OTP, transactional or promotional) and a contact person. Airtel and TNM approval usually takes 3–5 business days.
Balance
Your balance, credit limit and price per segment. available is what you can spend now.
| Billing type | How it works |
|---|---|
| Prepaid | Each message is charged when sent. available equals balance. UNDELIV messages are refunded. |
| Postpaid | You can spend up to your credit limit. available is balance plus limit. Invoiced monthly. |
Billing usage
Totals for a period: messages, segments, cost, delivered and undelivered counts, split by carrier.
| Query | Description | |
|---|---|---|
| from | Required | Start date, YYYY-MM-DD. |
| to | Required | End date, YYYY-MM-DD. |
Transactions
Every balance movement on your account, newest first: top-ups, SMS charges and refunds. Takes limit (default 50, maximum 500) and offset.
Create a webhook
Registers a URL that receives a POST for each delivery receipt (dlr) or inbound SMS (mo). This saves you from polling.
| Field | Type | Description | |
|---|---|---|---|
| url | string | Required | Your HTTPS endpoint. |
| events | array | Required | Any of dlr, mo, all. |
| secret | string | Optional | Sent back to you in the X-Webhook-Secret header so you can check that a call came from MeTicket. |
See Receiving webhooks for handler code.
List webhooks
Lists the webhooks on your account. Secrets are not returned.
Delete a webhook
Stops callbacks to that URL. Returns 404 if the webhook is not on your account.
Health
Service status and uptime in seconds. Use it for monitoring. GET / returns the service name and version, and GET /api/docs returns an endpoint index.
Webhook payloads
Each event is sent as a JSON POST with Content-Type: application/json, plus X-Webhook-Secret if you set one.
dlr
Sent when the carrier reports a final state for a message. Match it to your records by messageId. stat uses the values in Message statuses.
mo
Sent when someone replies to your Sender ID. Handle STOP and similar opt-out keywords.
Receiving webhooks
- Compare
X-Webhook-Secretto your secret and reject the call if they differ. - Reply with a
2xxwithin 5 seconds. Do slow work after you respond. - A call that times out or fails is not retried. If you miss one, read the result from the status endpoint.
- Make your handler safe to run twice for the same
messageId.
Segments & pricing
Long messages are split into segments and each segment is billed. Cost per recipient is segments × your price per SMS (see smsPriceMwk in Balance).
| Encoding | 1 segment | Per segment after that |
|---|---|---|
| GSM-7 | ≤ 160 chars | 153 chars |
| UCS-2 | ≤ 70 chars | 67 chars |
The HTTP API bills by the GSM-7 rule. Check long templates before a large send.
Cost calculator
- Characters
- —
- Segments
- —
- Per recipient
- —
- Total
- —
HTTP errors
| Code | Meaning | Common cause |
|---|---|---|
| 400 | Bad request | Missing to, from or message, or no valid numbers. |
| 401 | Unauthorized | API key missing or wrong. |
| 402 | Payment required | Balance or credit limit too low for the whole batch. |
| 403 | Forbidden | Sender ID not active on your account. |
| 404 | Not found | Message, Sender ID or webhook not on your account. |
| 429 | Too many requests | Over 60 API calls a minute. Back off and retry. |
| 500 | Server error | Contact support with the time and request. |
Send errors keep the SMSMessageData shape with an empty Recipients list. Other endpoints return {"error": "..."}.
SMPP connection
SMPP v3.4 is a persistent TCP connection for high volume. Use it if you send more than 50 messages a second, need the lowest latency, already run an SMPP client, or want inbound SMS in real time. Otherwise the REST API is simpler.
| Setting | Value |
|---|---|
| Host | smpp.meticketmw.com |
| Port | 2775 |
| System ID / password | Issued by MeTicket |
| Bind | bind_transceiver |
Required parameters
| Parameter | Value | Notes |
|---|---|---|
| source_addr_ton | 5 | Alphanumeric sender |
| source_addr_npi | 0 | Unknown |
| dest_addr_ton | 1 | International |
| dest_addr_npi | 1 | E.164 |
| data_coding | 0 | GSM-7 |
| esm_class | 0 | Default mode |
| enquire_link | 30 s | Keepalive, at least this often |
| wait_ack | 60 s | PDU response timeout |
| reconnect_delay | 10 s | Wait before reconnecting |
| max_sessions | 10 | Concurrent binds per account |
SMPP error codes
| Code | Hex | Meaning |
|---|---|---|
| ESME_ROK | 0x00000000 | Success |
| ESME_RINVPASWD | 0x0000000E | Wrong system ID or password |
| ESME_RBINDFAIL | 0x0000000D | Bind failed: account disabled or too many sessions |
| ESME_RTHROTTLED | 0x00000058 | Rate or session limit exceeded |
| ESME_RINVBNDSTS | 0x00000004 | PDU not allowed for this bind type |
| ESME_RINVDSTADR | 0x0000000B | Destination address missing or invalid |
| ESME_RINVESMCLASS | 0x00000043 | Invalid esm_class |
| ESME_RINVDCS | 0x00000104 | Unsupported data coding |
Rate limits
| Limit | Default | Notes |
|---|---|---|
| Messages per second | 10 per account | Extra numbers come back Throttled. MeTicket can raise it. |
| API requests | 60 per minute | Over this you get 429. |
| SMPP sessions | 10 | Concurrent binds. |
| Recipients per call | No hard limit | Keep batches at 1,000 or fewer. |
Best practices
- Keep the API key in an environment variable, never in source code.
- Check
statuson every recipient, not only the HTTP code. - Store every
messageId. You need it for status checks and support. - Use webhooks for delivery updates and poll only to fill gaps.
- Check your balance before a large send.
- Work out segments for long templates in advance with the calculator.
Go-live checklist
Support
Email sms@meticketmw.com. Include your systemId, the messageId and the time of the request so we can find it quickly.