General notes for SMS API users

Please note that this documentation is a work-in-progress and is subjected to minor changes based on requests and response bodies.

Language tab

If you are sending out messages in other languages, you can select the correct language tab before you key in your message content.

1. Message Content

   • Content in the message body field of each language is not automatically translated.

   • As a user, you will be required to input the correct language text into the message body field.

   • eg. If you select Malay as your language, you should input your message in Malay into the message body field; messages will not be translated for you.

2. SMS Header

   • SMS header will always remain in English.

3. SMS Footer

   • The SMS Footer of each message changes with the language selected.

   • eg. If you select Malay as your language, the SMS footer will change to Malay.

This site is for Postman v2, used for sending SMSes with the authorised sender ID only.

Test Platform

Test Environment

Production Platform

Production Environment

What types of data can Postman handle?

Postman can handle up to restricted sensitive-normal data.

Inquiries and FAQ

If you are a vendor with questions regarding our API documents, please indicate the contact details of the government officer-in-charge and their agency email address in your form response.

Campaign Creation and API keys for API users

Campaign creation should be the first step for all users, regardless if they are Admin portal, API users or SFTP users.

In order for API users to obtain the API keys for system integration, you will need to

1. Create Campaign and obtain a Campaign ID

Campaign Create Access

Postman will be implementing tighter access on creating campaigns.

From 20 May 2024, you will need to request for campaign create access from your agency person-in-charge (Agency PIC), before you can start creating campaigns. This change will be implemented on both our test and production platform.

How do identify my agency PICs?

You can idenfy your agency PICs by clicking on the ? button on your Postman dashboard.

Create Campaign

To start creating campaigns, select + Create campaigns on your home page

Campaign creation will consist of 3 steps:

1. Campaign Name

Upon clicking on + Create Campaign you will be taken to the campaign creation page and asked to name your campaign.

2. Channel Type

Postman has 2 types of campaign channels available - Member of Public and Internal Staff

1. Member of Public: To send out messages to MOPs

2. Internal Staff - to send out with your own sender ID

   • You will need to provide your own Twilio credentials if you choose the Internal Staff option

3. Campaign content

The campaign content is the content in the SMS that you will be sending out. You will be prompted to type out your campaign's message content.

There are different parts to the campaign content screen:

Message Preview

This is how your message will look like:

Header

The Header corresponds to the email account that you have logged into Postman with.

You may check on the email account that you've used to log into Postman by clicking on the avatar at the bottom right of the page. Refer to the image for more information

Changing your message header

Header name changes are permitted in specific cases, and approved on a case-by-case basis. Some examples where header name changes are permitted.

Platform products

An agency sending on behalf of another agency

Cases where header name changes are not permitted

If your agency has a project that sends out surveys or information on welfare packages etc, these do not qualify for header name changes.

Government Officers

Email login

If you selected email login, you will need to key in an OTP that is sent to your email address.

Agency users without a gov.sg email domain

• edu.sg

• synapxe.sg

• aic.sg

WOG Training Dates

The training dates below are for using the Postman v2 UI.

1. Campaign deletion features

You will no longer be able to do the following once a campaign is deleted

1. You cannot retrieve a deleted campaign:

   1. Campaign deletion is an irreversible process

2. No access to campaign

   1. No message can be sent out via this campaign, whether through the admin portal, API or SFTP

   2. No access to campaign logs - you will not be able to retrieve logs for this campaign

   3. No access to campaign or settings by all users except the agency's PIC

      1. This includes all members of the campaign that you have deleted

3. Unable to call the API endpoints with this campaign ID

   1. No access to campaign's settings, including API keys and whitelisted IP addresses

   2. Please synsure no one from your agency/vendors are using this campaign before deleting it

Actions that are still available after a campaign is deleted

1. Agencies will still be charged for messages sent from this campaign before campaign deletion

   1. Follows Postman billing

      1. Paid for by MDDI before 1 July 2025

      2. Paid for by your agency from 1 July 2025

      3. Refer to our billing page in our policy guide for more information

2. Agency Person(s) In-charge (PICs) will still be able to view deleted campaigns by users in their agency

   1. Able to do so via the Admin Dashboard

2. When should you delete campaigns

Scenario 1: Campaign created for testing purposes

You have created a campaign to test out how to create a campaign, send a message and how to access the campaign settings.

• No messages to MOPs were sent out through this campaign

You may delete this campaign as it is a campaign that you've created to try Postman out - the campaign was created for testing purposes.

• For API users: Before deleting this campaign, you should make sure that no other user/vendor is using this campaign when calling Postman’s API endpoints.

• If messages were sent out

  • Before 1 July 2025: messages paid for by MDDI

  • From 1 July 2025: messages paid for by your agency

Scenario 2: Campaign that is no longer in use

It is now December. You have created this campaign for an event in August. Messages were sent out via Postman to MOPs in the month of August and you are not using the campaign now.

• You are not planning to use this campaign now (December)

You should not delete this campaign as:

• You will no longer be able to retrieve campaign logs once you have deleted this campaign

  • you may need the logs when your agency is doing reconciliation of messages sent out by your agency

• This campaign is not being used now, but may be used again in the future.

3. Accessing campaign deleting feature

1. Click on the campaign you wish to delete on Postman's admin portal

2. Click on Settings
3. Click on Delete campaign

Message content

This flow allows you to create your own message in Postman using an editor and can be used by both admin portal and API users.

Message parameters (variables)

You can create multiple {{variables}} when typing out your message content. You can then input the values of each {{variable}}when you send the message from the admin portal or via API.

Variables have to fulfil the following in order to be successfully created

• Can only contain lowercase letters, numbers and _

• Must start with a lowercase letter

• If multiple languages are selected, the same variables must be present in all language tabs.

• Characters are within the GSM-7 character set. See section below on unsupported characters for more info.

Additional notes to message content

Unsupported characters

Postman message segment calculator

• identify avoidable characters within your message content

• identify non GSM characters within your message content

• check the number of message segments

This is what happens if you include unsupported characters in your messages:

1. unsupported characters changes the message encoding and therefore, significantly increases the number of message segments per SMS.

2. besides cost, long messages with multiple segments will jam the send queue, affecting even the campaigns of other agencies besides your own.

3. Reliability of sending messages cannot be guaranteed beyond 7 message segments per SMS, a limitation imposed by telcos. Hence, we advise you to keep your messages below 7 segments.

Blocking unsupported characters at the UI and API layers [English language only]

Message content containing unsupported characters will be blocked from sending.

1. On the UI:

Campaign templates that contain unsupported characters cannot be created on the UI/Postman admin portal. This blocking has been implemented since June 2024.

1. On the API:

If your message content is created only at the API layer, we will implement blocking on the Postman production environment from 5 May 2025. This blocking will be available on the Postman test environment from 17 February 2025.

Error message if your message contains unsupported characters at the API layer:

{
	"error": {
		"code": "parameter_invalid",
		"message": "Parameter values cannot contain avoidable expensive characters. Please refer to the guide (https://postman-v2.guides.gov.sg) to learn more.",
		"type": "domain_error",
		"id": "8758298681140894082"
	}
}

This is the list of characters* that are not supported by Postman and need to be excluded in the values.

• All emojis

• The following characters

*Note that \n is a way of representing a newline, and so will not be blocked on the API level.

Trailing white spaces in variables

Note that the content within your variables should not start nor end with a space, as this will trigger an error where your message will not be created (400 Bad Request).

eg. "Please report to Clinic A ."

In this example, contents in the variable are coloured, and the trailing spaces at the start/end of the variable content are highlighted in blue. The additional spaces will trigger an error where your message will not be created in Postman.

In the campaign dashboard, there are 2 categories:

Messages

Messages consists of all messages that you have sent out in a single campaign.

Messages may be sent out as a single message, or can be part of a batch of messages. You may identify this through the Job Type column in the campaign dashboard.

(Please ignore the details under From column.)

You will then receive the logs in your email, and you may filter out the required logs you will need using excel.

Each message will have its own message ID, this message ID can be found in the message logs that you download.

Batches

Similarly, you will receive the logs in your email, and you may filter out the required logs you will need using excel.

Retrieving logs by calling Postman API endpoints

Refer to the following pages to retrieve the message status for your campaigns

Postman allows a maximum of 1000 characters for a message body, excluding the header (agency’s name) and footer.

Agencies are strongly encouraged to limit their message body to 320 characters (excluding the header and footer) to avoid potential delays with message deliverability. As a precautionary measure, a warning message will appear for messages beyond 320 characters.

If the message body exceeds 1000 characters, the system will disable the ability to send the message. Message parameters, such as {{variable}} are not counted as characters. However, when these parameters are populated with actual values, the character count of the populated value is added to the overall character count.

For example:

• Message variable placeholder {{name}} is not included in the character count when crafting the message template.

• Filling the {{name}} variable with “Jonathan” adds 8 characters to the count

Use the Message Segment Tool before sending messages

Characters - English Language

The characters in a single text message include the following for "English" language*, with additional formatting details:

• Header: Free text field in message segment tool to type your agency name

• Line breaker (\n\n): 2 characters

• Slash icon ( --- ): 3 characters to separate sections

• Body: Free text field for your message content

• Line breaker (\n\n): 2 characters

• Slash icon ( --- ): 3 characters to separate sections

• Footer: 62 characters* for standardised "English" text used across all WOG messages

*Do note that the character count is different for other languages such as Chinese and Tamil.

Encoding used for English language

Enter your message template into the message segment tool to identify characters that are classified as GSM-7, non-GSM-7 and blocked characters in the "Underlying character codes" section.

Encoding used for English language

The encoding used for other languages (Chinese and Tamil) is Unicode, where both the footer contains either Chinese or Tamil characters.

Number of segment

A message segment refers to a portion of a text message when the total length exceeds 160 GSM-7 characters. If a single message is longer than 160 characters (including header and footer), it is divided into multiple segments. Each segment contains up to 160 GSM characters, including the header and footer. However, when a message uses more than one segment, the character limit per segment is reduced to 153 characters.

If the text message contains a Unicode encoding character, the maximum character count for one segment is 70 characters. If the Unicode message is longer than 70 characters (including header and footer), the character limit per segment is reduced to 67 characters.

You will be able to view how the message is broken up to multiple segments (as shown below) in “Message Parsed” and “Underlying Character Codes”, based on the character count, and this ensures that the character limits for each segment are properly managed.

Character count for message body

The character count applies only to the content typed in the free text box for the message template. The maximum number of characters Postman allows is 1000, excluding header and footer.

Total characters including header and footer

The total character count includes the entire messages including the agency name as the header, the body of the message and the standardised government text as the footer.

Estimated cost per SMS

Click on your campaign and the settings icon, this will open up your settings pop-up.

Settings - About

You will be able to view the following details

• Campaign ID

• Campaign Channel

• Campaign Message

• Download campaign logs

Settings - Members

Learn about the three types of access rights to Postman campaigns.

What are some special cases?

1. Non gov.sg domains that are considered government entities

   1. For now, this is limited to aic.sg, synapxe.sg, edu.sg

   2. *By default, every user with this domains has member access rights.

   4. Otherwise, all users with these domains can already log into Postman and view campaigns they have been added to (i.e. member access)

2. Vendors helping government entities with API integrations

   1. In such cases, Postman will not be granting vendors access to the portal. This means vendors with non-whitelisted email domains cannot log into Postman.

   2. Agency officers should log into Postman, create the campaign and craft the message, whitelist the IP addresses, generate the API keys and pass the API keys to the vendors for the necessary integration.

3. Vendors helping government entities send messages on Postman UI

   2. Vendors will then be able to log in and send messages, but not create campaigns i.e. member access

Integrations

Integrations are where you can whitelist your IP addresses and generate your API keys.

Integrations - IP address whitelisting

Provide your IP address for whitelisting. You will be able to provide up to 20 IP addresses.

Whitelist only

• Static IP addresses

• IP addresses that you are using to call the Postman API.

Connect to a VPN before calling the Postman APIs.

API Keys

You will only be able to obtain your API keys after you have whitelisted your IP address.

One campaign can have up to 3 API keys.

Do API keys have an expiry?

The API keys have no expiry.

If you need to obtain a new API key, you can simply delete the old key and generate a new key.

1. Register your desired Sender ID with SGNIC - note that these sender IDs should be used only for internal-facing SMSes.

2. Sign up for a Twilio account

3. Set Up your Twilio account

4. Configure your Twilio account

5. Send a test message on Twilio

6. Fill in your Twilio credentials in your campaign in Postman.

Now that you've decided to use Postman for your internal SMS campaigns, first ensure your desired Sender ID is registered under the Full SSIR Regime.

Some large agencies might already have registered their Sender IDs. This is especially the case for generic agency-name Sender IDs like MSF or MTI. If you are unsure if the Sender ID you would like to use has already been registered by your agency, please do check internally before submitting your registration.

How do I register for a Sender ID?

Using the Postman platform itself to send the SMSes are free.

However, there are 2 other costs that will need to be borne by agencies:

1. Sender ID registration costs (IMDA)

   • This is charged by IMDA for the registration and maintenance of your sender ID, which is a nation-wide regulation.

   • Total costs - one-time set-up fee of $500 per organisation + $200 annually per sender ID.

   • This is charged regardless of which aggregator you use.
2. Twilio per-SMS costs (Twilio)

   • This is charged by Twilio for each SMS that you send, at USD$0.0415 per message segment of 160 characters to send to recipients with Singapore numbers. Do note that the cost may vary depending on the country code of your recipient's mobile number.

Visit the following page for the latest updates on Postman's sending service and telco uptime

Non-GSIB laptops

GSIB laptops

1. What are the Postman SLOs?

• It is important to distinguish between the Service Level Objectives (SLOs) for Postman and the overall systems SLOs. Postman, as an integrated component within the larger system, has its own specific SLOs. Postman-specific SLOs focus on the performance, reliability, and efficiency of the Postman product itself. In other words, the Postman team is directly responsible for maintaining and monitoring these product-specific SLOs.

• In contrast, the overall system SLOs encompass the end-to-end performance of the entire integrated system, including Postman and all downstream components such as Tier 1 SMS Aggregators and Telcos.

• The Postman product contributes to the overall system performance. Therefore, our primary responsibilities and accountabilities lie with meeting and upholding the Postman-specific SLOs. The other individual players are held to their own SLOs and SLAs that are separate from Postman's SLOs with you.

• We actively manage and optimise Postman to meet these objectives, thereby ensuring our component's optimal contribution to the broader system performance.

2. What is Postman v2’s system uptime?

• Postman aims to have an uptime of >99.5%. We have internal services to monitor Postman uptime 24/7. These services send alerts if the product is down to the engineer-on-call, so that we can respond as soon as possible.

3. Any maintenance downtime for Postman v2?

• No, we will inform all users if there is going to be a scheduled downtime.

4. Subscribe to status updates:

• Typically, we inform users of downtime only if resolution is expected to take longer than a day, or if your campaign is directly affected.

5. How long can I expect a reply for my queries?

• Please ensure your requests are submitted via this form, rather than through emailing the team, as we are unable to respond as promptly to individual emails.

6. What are Postman's rate limits?

7. Where and when can I expect to be informed about updates to Postman?

• Where a product update is significant and will affect your workflows, we will communicate this through email blasts to all users of the Postman v2 test and production environments.

• We seek your understanding that as the product is still developing and the situation remains dynamic, changes may be made along the way, and may affect your current system set-ups. As far as possible, we will try our best to communicate this to you with significant heads-up for you to make the necessary preparations.

• We apologise in advance for cases where we inform of changes in a short span of time.

8. What is the expected deliverability standards i can expect for my campaign?

If you're 1) sending to local numbers, 2) Using only GSM characters, 3) less than 6 message segments, you can expect:

Overall Systems SLOs

Postman System SLOs

8. Please see the table below for guidelines on incident handling:

You will first need to configure your Twilio account to ensure that it is functioning and is mapped to your Sender ID.

1. Campaign Channel Type

Upon creating a campaign name, you will be taken to select the campaign channel type.

2. Adding Twilio Credentials

Select Internal Staff and scroll down to key in your Twilio Credentials.

Upon configuring your Twilio account, you will be able to obtain the necessary Twilio credentials required for you to input into your Postman campaign. More information can be found in Step 6. Fill in your Twilio credentials in Postman

Take note of the credentials you'll need to save-keep to input into Postman:

1. Account SID

An account SID is the unique identifier assigned to your agency account, much like an NRIC number. This is immediately available on your dashboard once you log into your account console.

1a. Account SID - Postman campaign settings

Insert your Account SID from your Twilio account console into Postman.

2. API key SID

To set up your API key for Postman, select API keys & tokens on the side dashboard under Accounts.

Then, create a new standard API key by selecting Create API key.

Create a friendly name for your API key so you can easily identify it in the future, and select Standard as the API key type.

You can find your API key under the Auth Tokens & API keys page.

2a. API Key SID - Postman campaign settings

Insert your API Key SID from your Twilio account console into Postman.

3. API Secret

When creating your API key, a secret key associated with your API key will be shown.

Save your secret key

Check the box and click Done.

3a. API Secret - Postman campaign settings

Insert your API Secret Key from your Twilio account console into Postman.

4. Message Service ID

This is the last detail you need to save before proceeding to Postman.

If you don't have a need to purchase a phone number, follow these steps to obtain your messaging service SID.

Go back to your Twilio home page, and select Set up a Messaging Service.

On the side bar, click Develop > Messaging > Services > Create Messaging Service.

Name your messaging service and indicate the purpose. This will help you better identify your use cases, especially if you have multiple, and will also help Twilio detect your specific use case quicker should you need their help for troubleshooting.

Set up your alphanumeric Sender ID

Configure your alphanumeric Sender ID by selecting Alpha Sender under Add Senders > Sender Type.

Click Continue. You may ignore the notification indicating that Alphanumeric Sender is not enabled for this account.

Specify the Alphanumeric Sender ID you want to use in the text box.

If the Alphanumeric Sender ID you chose is protected, you will notice either of the two things below.

• You encounter an error when setting it up on the Sender Pool page

• You may not receive any message when you send a test SMS

This also means that this Sender ID has been registered by another entity and you will not be able to use it.

Once you have completed the step above, you may click the Skip Setup button below.

After clicking "Skip setup" in the step above, you should be brought to the Properties page of this Messaging Service.

On this page, you should be able to find the Messaging Service ID.

4a. Message Service ID - Postman campaign settings

Insert your Messaging Service SID into Postman.

Expected Sender Name

Under your Expected Sender Name, enter your registered Sender ID.

To complete your set up, you will need to

1. Set up your account name

This helps us and Twilio better identify your account should you need help, without having to go into your account itself, which we prefer in order to respect the privacy and security of your account.

Go to Account > General settings > Account details > Account name.

2. Set up your billing details

Information about Twilio billing

Twilio works like a prepaid phone card. You will need to top up the credits in your Twilio account to start sending SMSes. We strongly recommend using your corporate credit card for this.

The alternative is direct invoicing, which is only available as an option if you send more than 25,000 SMSes a month (or meet the minimum spend of USD$12,000 annually). If this is your preferred option, please contact us so we can put you in touch with our Twilio account manager.

Note: if you do not upgrade your account, you will not be able to send SMSes with your registered alphanumeric Sender ID.

Set up Billing options - corporate credit card

To set up your billing options, go to Billing > Manage Billing > Upgrade.

3. Map your registered Sender ID to your Twilio account

You will need to prepare the following documents and submit them to Twilio via their application form.

As part of the Know-Your-Customer (KYC) processes, Twilio is required by IMDA to conduct checks on all approved Sender IDs submitted by organisations, before they can proceed to tag your SMSes with the Sender IDs after your campaign leaves the Postman gateway.

You will need to submit the following to Twilio, to get your sender IDs mapped:

1. ACRA BizFile Report

   • Bizfile Report should not be more than 3 months old

2. Proof of Registration with SSIR

   • Screenshot of confirmation that the Sender ID is registered with SSIR (Screenshot(s) should reflect Company Name and Sender ID approval)

3. Letter of Authorisation

Phone number purchase is necessary if you are sending SMSes to foreign numbers. Follow the steps here to purchase a number.

How to buy a phone number?

On the left console, select Develop > Phone Numbers > Manage > Buy a number.

Select the phone number that you prefer.

How to set up messaging service ID with phone number?

You need to create a messaging service and tie the phone number that you bought to this messaging service before you can send SMSes.

Go back to your Twilio home page, and selectSet up a Messaging Service.

On the side bar, click Develop > Messaging > Services > Create Messaging Service.

Name your messaging service and indicate the purpose. This will help you better identify your use cases if you have multiple, and will also help Twilio detect your specific use case quicker should you need their help for troubleshooting.

Add your Sender Pool. Sender Pool is where you configure the sender details such as the phone number you bought, and input your alphanumeric Sender ID.

Click Add Senders.

Add the phone number you purchased to this service.

Select the number you want to associate with this messaging service (if you have more than one).

To start sending out messages, select the campaign that you wish to use. This will take you to the campaign dashboard page. You may choose to send to a single recipient or multiple recipients

Single recipient

Upon selecting single recipient, a pop-up will prompt you to key in your recipient's details.

• Recipient's phone number

• Message language*

• Message parameters

Once the details have been filled in, click send to send out your message.

Formatting a single message

You may start entering fields into your message parameters.

Should there be a need to add commas or quotation marks in your message parameters, you may enter them in your message parameters.

Multiple recipients

Upon selecting multiple recipients, you will be prompted to upload a .csv file containing

• message parameters

We highly recommend the following steps when formatting your .csv file to send out messages

1. Download campaign .csv template

2. Edit the .csv template and save it as a .csv file

3. Upload your .csv file

In the multiple recipients sending format, any errors in the CSV file rows will result in failure to upload your file. You will need to fix the error(s) before all messages in the batch before you are able to successfully upload your file.

Recipient

This contains mobile phone number of the recipient, prefixed by the country code but without the leading +. For example, when sending to a Singapore phone number, the value of recipient will be 6599999999.

eg. 6591234567 is a recipient string for a Singapore (65) phone number (91234567)

Language

This column will need to be filled, even if there is only one available language that can be selected.

eg. If English is the only language you can choose in your message creation, you will need to fill every single entry with English.

Formatting messages to multiple recipients

You may start entering fields into each message parameter in your csv file.

Formatting in Excel

Excel: Commas and quotation marks

Should there be a need to add commas or quotation marks in your message parameters, you may enter them in each cell within your excel file.

Excel: Line Breaks

Should there be a need for line breaks, you may add them in a single cell

Formatting in text editor

Text Editor: Commas, line breaks, quotation marks

When formatting your messages in a text editor,

1. Ensure that all parameters are separated by commas

1. Should your content contain more than just letters, please encase them in quotations, see example above

   • Parameter containing more than just letters - highlighted in blue

2. Should your message content contain line breaks, please add the line breaks in your parameters within quotations, see image "Example csv in text editor".

1. Should your content contain quotation, encase the entire quote, including the quotation marks, within a set of quotations, see image "Example csv in text editor".

   • quote - highlighted in yellow

   • quotations used to encase quote - highlighted in pink

These steps will ensure that messages sent out can contain commas and quotation marks.

Postman Test Site: limitations

Postman's test site is meant for agency users to test out the platform. As such, you should test out the site like how you would send out messages to MOPs in a real scenario, where each number will only receive a single message.

If you send test messages with exact same content to the same person multiple times in 1 sitting in the same campaign:

eg. "Hi your appointment is on 1 Jan 2024" was sent to Tom 10 times within 1 batch send,

The telcos' automatic spam filter may be triggered . This means the message may not be delivered to Tom's phone at all, even though it will pass Postman’s send filters and status is reflected as delivered. See screenshot below on how the batch .csv is formatted in this failed example.

Your API keys carry many privileges, so be sure to keep them secure. Don't share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

curl https://<POSTMAN_V2_API_BASE_URL>/api/v2/campaigns/:campaignId/messages -H "Authorization: Bearer YOUR_API_KEY"

If you make a request without authentication, you will receive HTTP 401 and the following in your response body:

{
    "message": "Unauthorized",
    "statusCode": 401
}

Message

A message represents a message sent through a campaign.

As each campaign is associated with one message template and has its own API key, you will need to keep track of your API keys if you wish to send messages in different campaigns.

You will not be able to send or retrieve a message in a campaign inaccessible to yourself, even if you know the relevant ID(s).

Before calling Postman's API endpoints, please ensure

Multiple message parameters (variables)

In this example, we will be using the following message content with multiple message parameters (variables).

Dear {{name}}, your next appointment at {{clinic}} is on {{date}} at {{time}} hrs. 

Request Body example

{
    "recipient": "6599999999",
    "language": "english",
    "values": {
        // The following values are values for the parameters in the example template
        "name": "John Doe",
        "clinic": "Example Clinic",
        "date": "11 Dec 2023",
        "time": "11:30 am"
    }
}

CSV example for batch send

recipient,language,name,clinic,date,time
6599999999,ENGLISH,John Doe,Example Clinic,11 Dec 2023,11:30 am

API users who do not want to manage your message templates within Postman

If you are an API user that

• manages message templates within your own system

• uses Postman solely for sending out the full text of your message

you may create a single variable, {{body}}, and insert the message into the {{body}} variable.

Request Body example - single variable {{body}}

{
    "recipient": "6599999999",
    "language": "english",
    "values": {
    // The following values are values for the parameters in the example template
        "body": "Fill in your system constructed message here"
    },
}

CSV example for batch send - single variable {{body}}

recipient,language,body
6599999999,english,"Fill in your system constructed message here"

Line breaks in {{body}} messages

When formatting line breaks in your request body, please note the differences between

1. Single message

Single message

Request Body example - {{body}} and line breaks

{
    "recipient": "6599999999",
    "language": "english",
    "values": {
    // The following values are values for the parameters in the example template
        "body": "Dear Amy \n\nYour appointment for VACCINATION is confirmed.\n\nPlease do not reply to this message."
    },
}

For single message requests, you will be required to add the \n in your request body.

Batch messages

Postman only accepts .csv files for batch message. Take note of the differences when creating messages in excel and in a text editor.

For batch messages, do not to use \n to create line breaks, as the characters will be read as plain text and get sent out to MOPs

Text Editor

CSV example for batch send - {{body}} and line breaks

recipient,language,body
6591234567,english,"Dear Amy 

Your appointment for VACCINATION is confirmed.

Please do not reply to this message."
6599999999,english,"Dear John 

Your appointment for VACCINATION is confirmed.

Please do not reply to this message."

Your message in the {{body}} variable will need to be encased in "" if you are creating messages from a text editor.

Excel

Excel automatically adds "" to your file after you have saved it as a .csv file.

As such, do not encase the message in the {{body}} variable in "".

Postman Test Site limitations

Postman's test site is meant for agency users to test out the platform. As such, you should test out the site like how you would send out messages to MOPs in a real scenario, where each number will only receive a single message.

Multiple messages to the same user

If you send test messages with exact same content to the same person multiple times in 1 sitting in the same campaign:

eg. "Hi your appointment is on 1 Jan 2024" was sent to Tom 10 times within 1 batch send.

The telcos' automatic spam filter may be triggered . This means the message may not be delivered to Tom's phone at all, even though it will pass Postman’s send filters and status is reflected as delivered. See screenshot below on how the batch .csv is formatted in this failed example.

Postman v2 connects with Twilio to send out messages within the agency.

What is the difference between Twilio and Postman?

Postman is a free multi-channel communications platform built by Open Government Products for all public service agencies. Postman provides a convenient interface for you to craft your message, upload your recipient list, and send your campaign. Using Postman itself is free.

Twilio is a commercial cloud communication service that allows users to send messages (including SMS) through an Application Program Interface (API). Twilio bills users directly for its services; in this case, any SMSes you send using the Postman interface will be billed to you directly by Twilio. Postman does not pay for the SMSes that you send, but neither does Postman charge you for sending SMSes using our interface.

Why Twilio?

We evaluated other cloud-based SMS service providers like Nexmo and AWS SNS before we chose Twilio. We chose Twilio for its simple user interface with an interactive debugger. Its API documentation is also well written, and its API easy to set up. The API also optimises the rate limit to send bulk messages, and allow for users to retry for messages with errors during the first attempted delivery.

Importantly, Twilio API's success rate is 99.999% & uptime is around 99.95% monthly.

Since inception, we have used Twilio for SMS sending services, such as NDP ticketing, Digital MCs, SGH's elective surgery appointment reminders, and quarantine ops by MOH and ICA during Covid-19.

Can I trial using Postman to send SMSes before deciding whether to onboard onto Twilio?

Unlike Postman Legacy, Postman v2 does not offer users accounts with free demo campaigns.

You will need to have valid Twilio credentials, put them in Postman, and use this to send SMSes. You can send test SMSes to your own phone number, but this will be charged to your Twilio account directly.

Detailed explanation of error codes for specific troubleshooting steps

recipient_invalid error code

The recipient’s mobile number is not recognised by the network operator and cannot receive your SMS.

Common causes for recipient_invalid:

1. Deactivated or invalid number

   The recipient’s number might have been deactivated or is no longer in use.

2. Incorrect number format

   The mobile number may be incorrectly formatted when entering the number (e.g. wrong country code, missing digits).

Steps to troubleshoot:

1. Verify the mobile number.

2. Ensure your database is kept up to date by regularly validating the mobile numbers.

recipient_unavailable error code

The recipient’s device is not currently connected to the mobile network.

Common causes for recipient_unavailable:

1. Out of network coverage

   The recipient might be in an area with poor or no mobile network coverage, or there may be an ongoing issue with the telco operator.

2. SIM card issue

   The recipient’s SIM card may be malfunctioning or damaged, causing the device to fail to connect to the network.

3. Device issue

   There might be a technical issue with the handset, preventing it from connecting to the network.

Steps to troubleshoot:

1. Attempt to resend the message after some time.

2. Instruct the recipient to check if their SIM card is functioning properly. They can try inserting the SIM or testing it in another device to rule out SIM issues.

3. Ask the recipient to restart their device. If the problem persists, the recipient may need to reset their network settings, or consult their mobile operator for troubleshooting.

content_invalid error code

There is an issue with the message content, such as prohibited content or incorrect encoding.

Common causes for content_invalid:

1. Prohibited or sensitive content

   The message contains inappropriate keywords or phrases that are banned by the service provider.

2. Special characters or unsupported encoding

   Certain characters or symbols in the message (e.g., non-GSM characters, emojis) are not supported by the declared message encoding.

Steps to troubleshoot:

routing_error error code

There is a failure in routing the messages to the recipient’s mobile network.

Common causes for routing_error:

1. Mobile number is not released by the regulator

   The mobile number is not approved for messaging by the country's telecom regulator.

2. Networking routing configuration issue

   There is an issue with the mobile operator's routing infrastructure.

Steps to troubleshoot:

1. Confirm the mobile number is active and valid in the recipient's country.

message_expired error code

When a message from Postman is not delivered to the recipient handset within the 48-hour timeframe set by the SMS aggregators. This means that although the message was dispatched, it was not successfully delivered within the expected period, and its delivery status remains unknown.

Common cause for message_expired:

1. Delivery time frame exceeded

   Due to network delays, temporary issues with the aggregator's infrastructure may have caused delays in the message delivery.

Steps to troubleshoot:

1. It is unknown if the recipient has successfully received the message. You can consider resending critical messages.

delivery_unknown_error error code

The exact cause of the failure is not identifiable due to unknown configurations or issues on the recipient’s end. This means that while the message was sent successfully from Postman, the system cannot determine why it was not delivered.

Common causes for delivery_unknown_error:

1. Recipient's device configuration

   Unknown settings or configuration (e.g., third party mobile application, expired prepaid card) on the recipient's devices could affect the message delivery.

2. International restrictions

   Certain countries or regions may have restrictions on SMS delivery to specific number ranges, or certain carries may block messages from external providers.

Steps to troubleshoot:

2. For international restrictions issue, raise it to btn-ops@open.gov.sg and provide us with the message_ID of the affected messages.

server_unknown_error error code

This occurs when there is an internal error, typically due to an unknown issue with either Postman or the aggregator's server.

Common cause for server_unknown_error:

1. Temporary server outages

   One of the servers may experience temporary connectivity issues

Steps to troubleshoot:

1. For server issues, raise it to btn-ops@open.gov.sg immediately and provide us with the message_ID of the affected messages.

2. Once we have fixed the issue with the server, you may resend the message after some time.

We are using a Cursor-based pagination, a method of pagination that uses a unique identifier (cursor) to keep track of the current position in the dataset.

Here's a general overview of how it works:

2. Cursor: The before and after parameters are used to specify the cursor for fetching the previous or next page of results. The cursor typically represents the position of a specific record in the dataset.

3. Sorting: The data is sorted by the createdAt followed by id

4. Result: The response returns the paginated results along with cursors for the next and previous pages, allowing for easy navigation through the dataset.

{
  "data": [
    {
      "id": "message_62a2a141-97f8-4fc8-82db-36f539228322",
      "recipient": "6599999999",
      "values": {
        "recipientName": "Emily Yeo",
        "topic": "passport application #12345F"
      },
      "language": "english",
      "latestStatus": "success",
      "error": ""
    },
    ...
  ],
  "pageData": {
		"hasNextPage": false,
		"hasPreviousPage": false,
		"startCursor": "WyIyMDIzLTEwLTI0VDE3OjQwOjI1Ljk2OCswODowMCIsIm1lc3NhZ2VfM2E1MWI1ODctMzQ5OS00YTBmLTlkNGUtZTRlOWYzNWZkNmMxIl0=",
		"endCursor": "WyIyMDIzLTEwLTI0VDE3OjQwOjI1Ljk2OCswODowMCIsIm1lc3NhZ2VfM2E1MWI1ODctMzQ5OS00YTBmLTlkNGUtZTRlOWYzNWZkNmMxIl0="
	}
}

For example:

1. hasNextPage tells you if there's a next page in the queried data object

   1. To go to the next page, you can use the after Query Parameter with the current page's endCursor value.

2. hasPreviousPagetells you if there's a previous page in the queried data object

   1. To go to the previous page, you can use the before Query Parameter with the current page's startCursor value.

List of Apis that has pagination

The Postman v2 API is organised around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON response bodies, and uses standard HTTP response codes, authentication, and verbs.

https://<POSTMAN_V2_API_BASE_URL>/api/v2

Test Environment Base URL

Production Environment Base URL

Key information

1. The default rate limit is 10 TPS per campaign ID.

   -> This is defined as the number of API calls per second and not the number of messages sent per second.

2. This rate limit is shared across all APIs.

   -> For instance, if within your campaign you call the following:

   1. Single send at 6 TPS; and

   2. Retrieve message at 2 TPS; and

   3. Batch send at 4 TPS,

   then, as this adds up to 12 TPS, you will hit the rate limit and will be given a 429 error.

3. • In the form,

     1. state your use case

     2. state the ideal TPS needed, and reason needing this higher TPS.

     3. If you're asking for greater than 15 TPS, please provide evidence:

        1. You should provide us with internal logs of your actual historical cases on your old systems that you have hit that higher TPS before. Logs from testing on Postman are not considered proof.

        2. For instance, you can send us historical logs of maximum TPS experienced anytime from Jan 2022 onwards.

Things to note

1. The TPS limit applies only to messags entering the Postman system, not messages sent to the end recipients. Message delivery speeds may be slower than the TPS provided during peak periods, which occur from 8:00 am to 6:00 pm daily.

2. We will prioritise messages in the following manner:

   1. OTP messages using Single Send

   2. All other messages using Single Send

   3. All messages using Batch Send

3. Understand the difference between single and batch sending:

   1. If you're using single send, 1 TPS refers to 1 API call and 1 message to be sent out.

   2. If you're using batch send and you have 20 rows in your file, 1 TPS refers to 1 API call and 20 messages to be sent out.

Other important information

The Postman v2 API uses a number of safeguards against bursts of incoming traffic to help maximise its stability. If you send many requests in quick succession, you might see error responses that show up as status code 429.

Note that we do not queue requests which arrive past the rate limit and such requests are dropped. As such, you will need to retry the same request(s) later.

{
  "createdAt": "2024-05-16T10:30:50.904+08:00",
  "updatedAt": "2024-05-16T10:30:50.965+08:00",
  "id": "message_19e23cf4-6f0f-47ed-8856-4623817684b1",
  "recipient": "6599999999",
  "values": {
    "name": "John Doe",
    "fruit": "apple"
  },
  "creatorId": "<USER_ID_OF_MESSAGE_CREATOR>",
  "fullMessage": "<YOUR_FULL_MESSAGE>",
  "latestStatus": "success",
  "templateBodyId": "<YOUR_TEMPALTE_BODY_ID>",
  "campaignId": "<YOUR_CAMPAIGN_ID>",
  "templateBody": {
    "createdAt": "2024-05-16T10:13:15.111+08:00",
    "updatedAt": "2024-05-16T10:13:15.111+08:00",
    "id": "<YOUR_TEMPALTE_BODY_ID>",
    "templateId": "<YOUR_TEMPALTE_ID>",
    "language": "english",
    "body": "{{body}}",
    "creatorId": "user_200972fc-2aa5-42f5-b6fd-4023d96afcd4"
    
  },
  "batches": [],
  "language": "english",
  "creatorEmail": "campaign_93530a5f-9efd-4d4a-8b27-6a3770b815c2@postman.gov.sg",
  "attempts": [
    {
      "status": "success",
      "createdAt": "2024-05-16T10:57:52.534+08:00"
    },
    {
      "status": "failure",
      "createdAt": "2024-05-16T10:30:50.906+08:00",
      "error": {
        "type": "server_error",
        "code": "server_unknown_error"
      }
    }
  ]
}

Attributes

id string

creatorID string

Creator ID - this is the ID of the user that created the message on the first attempt

recipient numeric (Mandatory field)

For messages sent through the sms channel, the recipient will be the mobile phone number of the recipient, prefixed by the country code but without the leading +. For example, when sending to a Singaporean phone number, the value of recipient will be 6599999999

eg. 6591234567 is a recipient string for a Singapore (65) phone number (91234567)

language string (Mandatory field)

This is the language of the message template used to send this message. One of english, chinese, malay, or tamil.

values object (Mandatory field)

The values that were inserted into the message template and form the complete message. The keys within values will vary depending on the campaign’s template parameters.

In the example above, the message template that was used contained two parameters: recipient_name and topic.

Avoid using recipient and language as keywords as they are mandatory fields in the request payload.

fullMessage string

Contains the full message including the SMS Header and Footer.

campaignId string

Campaign identifier - this will inform you which campaign the message is tagged to.

unsupported characters

The GSM-7 character set is supported by Postman.

Otherwise, agencies should strictly abide by the unsupported character guidelines. This is the list of characters that are not supported by Postman and need to be excluded in the values.

This is what happens if you include unsupported characters in your messages:

1. unsupported characters significantly increase the character count and therefore, the number of message segments per SMS.

2. besides cost, long messages with multiple segments will jam the send queue, affecting even the campaigns of other agencies besides your own.

3. Reliability of sending messages cannot be guaranteed beyond 7 message segments per SMS, a limitation imposed by telcos. Hence, we advise you to keep your messages below 7 segments.

Trailing white spaces

latestStatus string

Possible message statuses and what they mean

attempts array of objects

Shows an object containing the status and createdAt for each attempt. If the status is failure , there will be an additional error object which includes:

1. type - The error type

   1. delivery_error - Error with the delivery of the message

   2. server_error

2. code - The error code

   1. recipient_invalid

   2. recipient_unavailable

   3. content_invalid

   4. routing_error

   5. delivery_unknown_error

   6. server_unknown_error

The full description of each error code can be found in the Message delivery errors page

Billing and Costs

If you are unable to obtain a corporate credit card, you can explore direct invoicing with Twilio. However, Twilio requires a minimum spend of US12,000 annual (or about 25,000 SMSes per month) to qualify for this mode of payment.

What is the cost?

At this point of writing (March 2024), it costs USD$0.0415 per message segment of 160 characters to send to recipients with Singapore numbers. If your message is longer than 160 characters, you will be charged the cost of as many message segments.

Before creating a Twilio account

You will need the following before signing up for a Twilio account:

1. Email address: This email address will be associated with the Twilio account that you are signing up for

2. Mobile Number: This number will be receiving security codes required when logging into your Twilio account.

Creating a Twilio account

2. Upon signing up for a free account on Twilio, you will be taken to your Twilio Console Dashboard Homepage.

Retries a single failed message. The message will retain the same message ID.

The message retry will only go through if:

1. The message latestStatus is failure

2. If the message belongs to a batch, the batch status is either messages_enqueued or messages_enqueuing_failed

After a message is retried, the message latestStatus will be set to created.

[Now to 26 Jan 2025] Example response body

[From 24 Feb 2025] The creatorId field will be inserted in the response payload from 24 Feb 2025. Please amend your own code accordingly for

"creatorId": "<USER_ID_OF_MESSAGE_CREATOR>"

The keys within the values object will vary depending on the campaign’s template parameters. To find out what the parameters for a template are, please refer to the template’s details in Postman’s web interface.