DEVELOPER DOCUMENTATION
Messaging API
Send SMS and email messages from your applications through a secure REST API.
Techage Messaging provides a JSON-based endpoint for submitting messages to one or more recipients.
Every request is authenticated with an organization-owned API token. The API supports SMS, email, or both channels in the same submission.
PRODUCTION BASE URL
https://api.messaging.techageltd.com/api/v1 MESSAGE ENDPOINT
/messages Authentication
Authenticate every request with an organization API token using the HTTP Bearer scheme.
Generate a token inside Techage Messaging under More → For Developers. Give it a descriptive name and copy the credential immediately.
Tokens are displayed only once. Store them securely on your backend, never in public frontend code.
REQUEST HEADER
Authorization: Bearer YOUR_API_TOKEN
CONTENT TYPE
Content-Type: application/json
Invalid or revoked credentials return HTTP 401.
Send a message
Queue an SMS, email, or both in a single request.
/messages Supply at least one enabled channel and the message content.
For SMS, include an approved sender name and recipient mobile numbers. For email, include recipient email addresses and a subject.
EXAMPLE REQUEST
curl --request POST "https://api.messaging.techageltd.com/api/v1/messages" \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: order-1042-sms-v1" \
--data '{
"sms": true,
"email": false,
"sendername": "YOUR_APPROVED_SENDER",
"mobileNo": ["233XXXXXXXXX"],
"message": "Your order is ready."
}' // Server-side JavaScript (Node.js)
const url = "https://api.messaging.techageltd.com/api/v1/messages";
const token = process.env.TECHAGE_API_TOKEN;
const response = await fetch(url, {
method: "POST",
headers: {
Authorization: "Bearer " + token,
"Content-Type": "application/json",
"Idempotency-Key": "order-1042-sms-v1"
},
body: JSON.stringify({
sms: true,
email: false,
sendername: "YOUR_APPROVED_SENDER",
mobileNo: ["233XXXXXXXXX"],
message: "Your order is ready."
})
});
const result = await response.json();
if (!response.ok) {
throw new Error(JSON.stringify(result));
}
console.log(result); # Python 3 (server-side)
import os
import requests
url = "https://api.messaging.techageltd.com/api/v1/messages"
token = os.environ["TECHAGE_API_TOKEN"]
response = requests.post(
url,
headers={
"Authorization": f"Bearer {token}",
"Idempotency-Key": "order-1042-sms-v1",
},
json={
"sms": True,
"email": False,
"sendername": "YOUR_APPROVED_SENDER",
"mobileNo": ["233XXXXXXXXX"],
"message": "Your order is ready.",
},
timeout=30,
)
result = response.json()
response.raise_for_status()
print(result) <?php
// PHP 8+ with the cURL extension.
$token = getenv("TECHAGE_API_TOKEN");
if (!$token) {
throw new RuntimeException("Missing API token");
}
$payload = [
"sms" => true,
"email" => false,
"sendername" => "YOUR_APPROVED_SENDER",
"mobileNo" => ["233XXXXXXXXX"],
"message" => "Your order is ready.",
];
$ch = curl_init("https://api.messaging.techageltd.com/api/v1/messages");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . $token,
"Content-Type: application/json",
"Idempotency-Key: order-1042-sms-v1",
],
CURLOPT_POSTFIELDS => json_encode(
$payload,
JSON_THROW_ON_ERROR
),
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
if ($response === false) {
$error = curl_error($ch);
curl_close($ch);
throw new RuntimeException($error);
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode(
$response,
true,
512,
JSON_THROW_ON_ERROR
);
if ($status >= 400) {
throw new RuntimeException(
"API error: " . json_encode($result)
);
}
print_r($result); require "net/http"
require "json"
require "uri"
# Server-side Ruby using standard libraries.
url = URI("https://api.messaging.techageltd.com/api/v1/messages")
token = ENV.fetch("TECHAGE_API_TOKEN")
payload = {
sms: true,
email: false,
sendername: "YOUR_APPROVED_SENDER",
mobileNo: ["233XXXXXXXXX"],
message: "Your order is ready."
}
request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer #{token}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "order-1042-sms-v1"
request.body = JSON.generate(payload)
response = Net::HTTP.start(
url.hostname,
url.port,
use_ssl: url.scheme == "https",
open_timeout: 10,
read_timeout: 30
) do |http|
http.request(request)
end
result = JSON.parse(response.body)
unless response.is_a?(Net::HTTPSuccess)
raise "API request failed: #{result}"
end
puts JSON.pretty_generate(result) Request parameters
Send a JSON object containing the required fields for the channels you want to use.
sms and
email, even when one is false.
At least one must be true.
Recipient formats
Both mobileNo and
emailAddress accept either
a single string or
an array of strings.
"mobileNo": "233XXXXXXXXX" "mobileNo": ["233XXXXXXXXX", "233YYYYYYYYY"] | Parameter | Description |
|---|---|
sms boolean Yes | Always required. Set true to send SMS or false to disable SMS. At least one channel must be true. |
email boolean Yes | Always required. Set true to send email or false to disable email. At least one channel must be true. |
message string Yes | Message content. Required for every submission. |
sendername string If SMS | An approved sender name belonging to your organization. |
mobileNo string | string[] If SMS | Accepts a single phone-number string OR an array of phone-number strings. Comma-separated strings are not supported. |
emailAddress string | string[] If email | Accepts a single email-address string OR an array of email-address strings. Comma-separated strings are not supported. |
subject string If email | Subject of the email message. |
Recipient fields accept a string or an array of strings. Comma-separated recipient strings are not accepted. Recipient validity is evaluated during message estimation.
REQUEST BODY EXAMPLES
{
"sms": true,
"email": false,
"sendername": "YOUR_APPROVED_SENDER",
"mobileNo": [
"233XXXXXXXXX",
"233YYYYYYYYY"
],
"message": "Your order is ready."
} {
"sms": false,
"email": true,
"emailAddress": [
"customer@example.com"
],
"subject": "Order notification",
"message": "Your order is ready."
} {
"sms": true,
"email": true,
"sendername": "YOUR_APPROVED_SENDER",
"mobileNo": [
"233XXXXXXXXX"
],
"emailAddress": [
"customer@example.com"
],
"subject": "Order notification",
"message": "Your order is ready."
} Idempotency
Use the optional
Idempotency-Key
header to prevent accidental
duplicate submissions.
This is particularly useful when your application experiences a timeout and needs to retry a request.
Returns the existing message batch.
Returns HTTP 409 IDEMPOTENCY_CONFLICT.
1–128 printable ASCII characters, without spaces.
Idempotency keys are scoped to the API token. Reuse a key only when intentionally retrying the same submission.
OPTIONAL REQUEST HEADER
Idempotency-Key: order-1042-sms-v1
IDEMPOTENT REPLAY · HTTP 200
{
"status": "pending",
"message_batch_id": 123,
"idempotent_replay": true
} Responses
A successful submission returns HTTP 200 with a batch identifier.
The returned
message_batch_id
identifies the recorded message
batch.
status
New accepted submissions
return queued.
A replay returns the
stored batch status.
message_batch_id Identifier assigned to the submission.
idempotent_replay
Present as true
when an existing batch
is returned.
SUCCESS RESPONSE
{
"status": "queued",
"message_batch_id": 123
} {
"status": "pending",
"message_batch_id": 123,
"idempotent_replay": true
} Errors
Failed requests return a JSON error with a machine-readable code and a human-readable message.
| HTTP | Error code | Meaning |
|---|---|---|
400 | BAD_REQUEST | Missing required request fields. |
400 | INVALID_RECIPIENT_FORMAT | Invalid recipient structure. |
400 | INVALID_IDEMPOTENCY_KEY | Invalid idempotency header. |
400 | NO_VALID_RECIPIENTS | No valid recipients found. |
401 | INVALID_TOKEN | Invalid or revoked API token. |
402 | INSUFFICIENT_BALANCE | Insufficient messaging units. |
403 | INVALID_SENDER_NAME | Sender name is not approved. |
403 | ORGANIZATION_UNAVAILABLE | No active execution account. |
409 | IDEMPOTENCY_CONFLICT | Key reused with different content. |
413 | REQUEST_TOO_LARGE | Request exceeds 2 MB. |
429 | RATE_LIMIT_EXCEEDED | API request limit exceeded. |
429 | INVALID_TOKEN_RATE_LIMITED | Authentication backoff active. |
503 | MESSAGE_QUEUE_PENDING_RECOVERY | Dispatch pending recovery. |
503 | MESSAGE_QUEUE_FAILED | Message queue failure. |
Some errors include
details.errors.
Failures involving an existing
batch may also include
message_batch_id.
ERROR RESPONSE EXAMPLES
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request parameters",
"details": {
"errors": [
"message is required",
"mobileNo is required when sms is set to true"
]
}
}
} {
"error": {
"code": "INVALID_TOKEN",
"message": "Invalid or revoked API credential."
}
} {
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "You need 5 units but only have 2. Shortfall: 3"
},
"message_batch_id": 123
} Rate limits
The API enforces request limits to protect the messaging platform.
More than ten invalid authentication attempts within one minute can trigger the five-minute backoff.
HTTP 429 responses contain a
Retry-After header.
Respect it before retrying.
HTTP 429 · RATE LIMIT
Retry-After: 60 {
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Maximum 60 API requests per minute. Please try again shortly."
}
} Best practices
Protect your API token
Store credentials in a secure backend environment or secrets manager.
Validate recipients
Check recipient details before submission.
Retry carefully
Use idempotency keys and respect retry headers. Don't blindly resend after an uncertain outcome.
Handle delivery separately
API acceptance is not a delivery confirmation.
Use approved sender names
SMS sender names must be approved for your organization.
PRODUCTION CHECKLIST
✓ HTTPS enabled
✓ API token stored server-side
✓ Approved sender name configured
✓ Recipient validation implemented
✓ Errors handled appropriately
✓ Safe retry strategy configured
Support
Need assistance with API integration, authentication, sender names or message-submission errors?
Contact the Techage support team using the details alongside.
Techage Ltd · Ghana
CONTACT TECHAGE
Techage Messaging API · Version 1.0.0