Techage Messaging

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.

API version 1.0.0 · JSON over HTTPS

PRODUCTION BASE URL

https://api.messaging.techageltd.com/api/v1

MESSAGE ENDPOINT

POST /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.

Each organization can maintain up to 3 active API tokens. Revocation is permanent.

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.

POST /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.

Replace the sample sender name, recipient number and token with your own valid values before executing a request.

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."
  }'

Request parameters

Send a JSON object containing the required fields for the channels you want to use.

Required channel flags: Always include both 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.

Single recipient "mobileNo": "233XXXXXXXXX"
Multiple recipients "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."
}

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.

Same key + same request

Returns the existing message batch.

Same key + different request

Returns HTTP 409 IDEMPOTENCY_CONFLICT.

Key format

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.

An accepted submission does not guarantee that the recipient has received the message.

SUCCESS RESPONSE

{
  "status": "queued",
  "message_batch_id": 123
}

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"
      ]
    }
  }
}

Rate limits

The API enforces request limits to protect the messaging platform.

60 Authenticated submissions per minute, per API token
2 MB Maximum request body size
5 min Authentication backoff following excessive invalid-token attempts

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.

When reporting an API issue, include the relevant error code and batch ID, if available. Never share your complete API token.

Techage Ltd · Ghana

CONTACT TECHAGE

Technical support support@techageltd.com
General enquiries info@techageltd.com
Telephone +233302815789

Techage Messaging API · Version 1.0.0