Overview

MAE enables customers to send and receive SMS and MMS messages. It is a collection of REST API calls that support outbound messaging, inbound message callbacks, delivery notifications, and media handling.

Authorization Process

Aizan authentication follows an OAuth2 client-credentials flow. During onboarding, customers receive credentials that are exchanged for a Bearer token. The token expires periodically and must be refreshed before continuing to call MAE APIs.

DID Assignment

During onboarding, customers also receive a local 10-digit DID mapped to their account. This DID is used as the source, or From, number for outbound messaging requests.

Base URL

Production: https://cloudapi.aizan.com/mae/
Sandbox: https://stagingcloudapi.aizan.com/mae/

Authorization

All requests must be authenticated. Aizan APIs use OAuth2 through AWS Cognito for token generation, allowing enterprise-grade authentication before SMS, MMS, media, and callback workflows are used.

Authentication

Authorization is performed with a POST request to the token URL. The request contains a Basic Authorization header with the customer's encoded credentials and a form body containing grant_type=client_credentials.

POST https://cloudauth.aizan.com/oauth2/token

Error code details

Error Code	Message
400	Bad Request
500	Internal Server Error

Response

200 Object OK

Response Attributes

access_token string

Bearer token used for authenticated MAE requests.

expires_in string

Lifespan of the token in seconds.

token_type string

Token type returned by the identity provider.

Request

curl --location 'https://cloudauth.aizan.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic BASE64ENCODED_LOGIN:PASSWORD' \
  --data-urlencode 'grant_type=client_credentials'

Response

{
  "access_token": "[Bearer Token]",
  "expires_in": "[Expiry Time]",
  "token_type": "Bearer"
}

SMS Outbound Request

SMS Outbound Request initiates a customer message request to a mobile user.

Customer makes a request to the MAE API.
MAE validates the request and passes the message for delivery.
A delivery callback is sent to the configured customer URL.

POST https://cloudapi.aizan.com/mae/sms/v1/outbound

Header Parameters

Authorization string required

Bearer token returned from the authorization request.

Body Parameters

source string required

10-digit DID assigned to the customer account.

destination string required

Mobile number receiving the SMS message.

messageText string required

Text body of the outbound SMS.

Response

200 Object Message accepted

Language Box

POST /sms/v1/outbound

curl --location 'https://cloudapi.aizan.com/mae/sms/v1/outbound' \
  --header 'Authorization: Bearer {Token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "12262122660",
    "destination": "14166888292",
    "messageText": "Hello World!"
  }'

Response

{
  "source": "224900451452",
  "destination": "490045145222",
  "messageText": "Hello",
  "messageId": "e77a9a77-4f18-4f7b-ae92-6d7984558fb3"
}

MMS Outbound Request

MMS Outbound Request sends a multimedia message from an assigned DID to a destination number. Media must be created first and sent by referencing one or more media IDs.

POST https://cloudapi.aizan.com/mae/mms/v1/outbound

Header Parameters

Authorization string required

Bearer token returned from the authorization request.

Body Parameters

source string required

10-digit DID assigned to the customer account.

destination string required

Mobile number receiving the MMS message.

messageText string optional

Text included with the MMS payload.

mediaId array required

Media IDs returned by the media creation request.

Error code details

Error Code	Message
400	Invalid Request
401	Unauthorized access
500	Internal Server Error

Language Box

POST /mms/v1/outbound

curl --location 'https://cloudapi.aizan.com/mae/mms/v1/outbound' \
  --header 'Authorization: Bearer {Token}' \
  --data '{
    "source": "12262122660",
    "destination": "14166888292",
    "messageText": "Hello!",
    "mediaId": [
      "6b512106-d537-493d-9ecd-5f597d0bbe97"
    ]
  }'

Response

{
  "source": "224900451452",
  "destination": "490045145222",
  "messageText": "Hello",
  "messageId": "e77a9a77-4f18-4f7b-ae92-6d7984558fb3",
  "mediaId": [
    "6b512106-d537-493d-9ecd-5f597d0bbe97"
  ]
}

Media Creation Request

Media Creation Request uploads media content and returns a media ID. That media ID can then be referenced by outbound MMS requests.

POST https://cloudapi.aizan.com/mae/media/v1/files

Header Parameters

Authorization string required

Bearer token returned from the authorization request.

media-part string required

Indicates the uploaded media type and content part.

Supported media types

image	Use an image media payload.
audio	Use an audio media payload.
video	Use a video media payload.
pdf	Use a PDF media payload.

Language Box

POST /media/v1/files

curl --location 'https://cloudapi.aizan.com/mae/media/v1/files' \
  --header 'media-part: application/octet-stream' \
  --header 'media-part: image' \
  --header 'Authorization: Bearer {Token}' \
  --data '{
    "controlPart": {
      "fileName": "unnamed.png",
      "fileType": "image"
    },
    "mediaPart": {
      "contentType": "application/octet-stream",
      "mediaContent": "<Base64>"
    }
  }'

Response

{
  "mediaId": "59d6b444-2b05-4b2e-9d03-e91118784217",
  "fileName": "59d6b444-2b05-4b2e-9d03-e91118784217.png",
  "type": "image",
  "createdDts": "2023-09-26T07:10:00.106354"
}

Delivery Callback

Delivery callbacks notify the customer system as delivery status changes. Aizan sends the callback to the customer-provided URL configured during onboarding.

Body Parameters

messageId string

Message identifier returned by the outbound request.

deliveryStatus string

Current delivery state for the message.

from string

Source DID used by the outbound message.

to string

Destination mobile number.

Status values

PENDING	Message delivered to the SMS carrier.
DELIVERED	Message delivered to the recipient carrier.
HANDSET DELIVERED	Message delivered to the recipient handset when supported.
ERROR	Exception occurred during processing or delivery.

Language Box

customer-provided-url

curl --location 'https://cloudapi.aizan.com/mae/customer-provided-url' \
  --header 'Authorization: Bearer {Token}' \
  --data '{
    "messageId": "48c90962-9318-4510-a434-67a77ec355b0",
    "deliveryStatus": "DELIVERED",
    "from": "12262122660",
    "to": "14166888292"
  }'

Response

200 OK

Inbound Message Callback

Inbound message callbacks notify the customer system when a mobile user sends a message to an assigned DID. Aizan posts the inbound payload to the configured customer URL.

Body Parameters

messageId string

Unique identifier for the inbound message.

from string

Mobile user sending the message.

to string

Customer DID that received the message.

message string

Inbound text message content.

Response

200 Object Callback acknowledged

Language Box

customer-provided-url

curl --location 'https://cloudapi.aizan.com/mae/customer-provided-url' \
  --header 'Authorization: Bearer {Token}' \
  --data '{
    "messageId": "48c90962-9318-4510-a434-67a77ec355b0",
    "from": "12262122660",
    "to": "14166888292",
    "message": "Hello World!"
  }'

Response

200 OK