MeTicket Developers
MeTicket Developers SMS API v3.0
Airtel Malawi + TNM Malawi

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
Start

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.

Your app your server POST /send webhook MeTicket Gateway 1Check your API key 2Check your Sender ID 3Charge per segment 4Pick network by prefix 5Queue, then submit 6Track delivery SMPP DLR SMPP DLR Airtel SMSC TNM SMSC Phone 099… 098… Phone 088… 085… Solid lines: your message going out. Dashed lines: delivery reports coming back.

The life of one message

  1. You send a request

    Your server POSTs the number, your Sender ID and the text to /api/messaging/send.

  2. 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.

  3. 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.

  4. 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.

  5. The network takes it

    The gateway sends the message to Airtel or TNM over SMPP. Once the network accepts it, the status becomes ENROUTE.

  6. 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.

  7. The network reports back

    The network sends a delivery receipt (DLR). The status becomes DELIVRD, or UNDELIV if delivery failed. Prepaid accounts get an UNDELIV message refunded.

  8. 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

WhenStatusHow you know
InstantlySUBMITTEDSend response
~1 secondENROUTEStatus endpoint
Seconds to hoursDELIVRDWebhook or status
Seconds to hoursUNDELIVWebhook 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

  1. 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.

  2. Check the key works

    Call GET /api/auth/whoami. You get your account, billing type, balance and price per SMS back.

  3. Send your first SMS

    POST to /api/messaging/send with to, from and message. Save the messageId from 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:

HeaderNotes
Authorization: ApiKey <key>Preferred
X-API-Key: <key>Alternative
GET/api/auth/whoamiApiKey

Use whoami to confirm the key and read your account settings.

Security

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.

CarrierPrefixesExample
Airtel265 99 · 98 · 97 · 91+265991234567
TNM265 88 · 85 · 84 · 83+265881234567
FallbackAny other prefixRouted 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.

SUBMITTED→ENROUTE→DELIVRDorUNDELIV
StatusMeaningWhat to do
SUBMITTEDAccepted by the gateway and queued for the carrier.Wait.
ENROUTEHanded to the Airtel or TNM SMSC. Waiting for the handset.Wait. Phones that are off can take hours.
DELIVRDThe carrier confirmed delivery to the handset.Final.
UNDELIVThe carrier could not deliver. Prepaid accounts are refunded automatically.Final. Check the number.
FAILEDNot sent, because of balance or a carrier error.Final. Check balance, then retry.
CANCELLEDStopped before it reached the carrier.Final.
Endpoints

Send SMS

POST/api/messaging/sendApiKey

Sends one message to one or more numbers. Each number is routed, charged and queued on its own, and gets its own messageId.

Body

FieldTypeDescription
tostring | arrayRequiredOne number, a comma-separated string, or a JSON array. E.164 preferred.
fromstringRequiredYour Sender ID. It must be ACTIVE on your account.
messagestringRequiredMessage text. Up to 160 characters is 1 segment; longer text is billed in 153-character segments.
carrierstringOptionalairtel or tnm to skip automatic routing.

Response

FieldDescription
MessageSummary, such as Sent to 3/3 contacts.
Recipients[].statusSuccess or Throttled. A throttled number was not sent and has no messageId; send it again later.
Recipients[].statusCode101 on success.
Recipients[].messageIdUUID for status checks, DLRs and support requests. Store it.
Recipients[].carrierairtel or tnm.
Recipients[].costAmount charged, such as MWK 3.50.
Check each number

A 200 means the request was accepted, not that every number was sent. Read status on each recipient.

Encoding

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

POST/api/messaging/sendApiKey

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

GET/api/messaging/{messageId}/statusApiKey

Returns the current status of one message, with the time it was sent and the time it was delivered.

PathDescription
messageIdThe 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

GET/api/messaging/{messageId}/dlrsApiKey

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

GET/api/messagingApiKey

Lists your messages, newest first.

QueryDefaultDescription
limit50Page size. Maximum 500.
offset0Rows to skip.
status—Filter, such as DELIVRD or UNDELIV.

Get a message

GET/api/messaging/{messageId}ApiKey

Returns the full stored record for one message: text, sender, segments, cost and timestamps.

Carrier status

GET/api/messaging/carriersApiKey

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

GET/api/messaging/usage/summaryApiKey

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

GET/api/senderidsApiKey
GET/api/senderids/{id}ApiKey

Lists the Sender IDs on your account. Only those with status: "ACTIVE" work in the from field.

Sender ID formats

TypeFormatExample
Alphanumeric3–11 letters and digits, at least one letterMYBANK
Numeric5–15 digits265999
Short code3–6 digits1234
New Sender ID

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

GET/api/billing/balanceApiKey

Your balance, credit limit and price per segment. available is what you can spend now.

Billing typeHow it works
PrepaidEach message is charged when sent. available equals balance. UNDELIV messages are refunded.
PostpaidYou can spend up to your credit limit. available is balance plus limit. Invoiced monthly.

Billing usage

GET/api/billing/usageApiKey

Totals for a period: messages, segments, cost, delivered and undelivered counts, split by carrier.

QueryDescription
fromRequiredStart date, YYYY-MM-DD.
toRequiredEnd date, YYYY-MM-DD.

Transactions

GET/api/billing/transactionsApiKey

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

POST/api/webhooksApiKey

Registers a URL that receives a POST for each delivery receipt (dlr) or inbound SMS (mo). This saves you from polling.

FieldTypeDescription
urlstringRequiredYour HTTPS endpoint.
eventsarrayRequiredAny of dlr, mo, all.
secretstringOptionalSent 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

GET/api/webhooksApiKey

Lists the webhooks on your account. Secrets are not returned.

Delete a webhook

DELETE/api/webhooks/{id}ApiKey

Stops callbacks to that URL. Returns 404 if the webhook is not on your account.

Health

GET/healthNo auth

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.

Reference

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-Secret to your secret and reject the call if they differ.
  • Reply with a 2xx within 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).

Encoding1 segmentPer segment after that
GSM-7≤ 160 chars153 chars
UCS-2≤ 70 chars67 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

CodeMeaningCommon cause
400Bad requestMissing to, from or message, or no valid numbers.
401UnauthorizedAPI key missing or wrong.
402Payment requiredBalance or credit limit too low for the whole batch.
403ForbiddenSender ID not active on your account.
404Not foundMessage, Sender ID or webhook not on your account.
429Too many requestsOver 60 API calls a minute. Back off and retry.
500Server errorContact 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.

SettingValue
Hostsmpp.meticketmw.com
Port2775
System ID / passwordIssued by MeTicket
Bindbind_transceiver

Required parameters

ParameterValueNotes
source_addr_ton5Alphanumeric sender
source_addr_npi0Unknown
dest_addr_ton1International
dest_addr_npi1E.164
data_coding0GSM-7
esm_class0Default mode
enquire_link30 sKeepalive, at least this often
wait_ack60 sPDU response timeout
reconnect_delay10 sWait before reconnecting
max_sessions10Concurrent binds per account
Node.js · npm install smpp

SMPP error codes

CodeHexMeaning
ESME_ROK0x00000000Success
ESME_RINVPASWD0x0000000EWrong system ID or password
ESME_RBINDFAIL0x0000000DBind failed: account disabled or too many sessions
ESME_RTHROTTLED0x00000058Rate or session limit exceeded
ESME_RINVBNDSTS0x00000004PDU not allowed for this bind type
ESME_RINVDSTADR0x0000000BDestination address missing or invalid
ESME_RINVESMCLASS0x00000043Invalid esm_class
ESME_RINVDCS0x00000104Unsupported data coding

Rate limits

LimitDefaultNotes
Messages per second10 per accountExtra numbers come back Throttled. MeTicket can raise it.
API requests60 per minuteOver this you get 429.
SMPP sessions10Concurrent binds.
Recipients per callNo hard limitKeep batches at 1,000 or fewer.

Best practices

  • Keep the API key in an environment variable, never in source code.
  • Check status on 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.