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.

WOG Training Dates

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

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:

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, and is compliant with the new-IM8 policy for Low-Risk systems.

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.

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

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.

Possible replacements to unsupported characters

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.

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:

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

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.

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.

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.

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.

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.

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

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.

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.

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

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

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
}

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.

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

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

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.

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 uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate a request that failed given the information provided (e.g., a required parameter was omitted, not having access to the campaign due to wrong API key, etc.). Codes in the 5xx range indicate an error with Postman’s servers (these will be rare).

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

Attributes

message string

A human-readable message providing more details about the error.

statusCode number

The HTTP status code of the error.

HTTP status code summary

Send a test message on Twilio

Note that this step is done in Twilio, not Postman, yet.

Navigate back to the console and under Try it out, select Send an SMS. Insert your own phone number and select the messaging service that you set up earlier in step 4.

Type your message and click send to check if you receive the SMS and if the Sender ID is accurate.

If you encounter an error with sending a test SMS, it is likely that the Sender ID has yet to be mapped to Twilio. You may reach out to us so that we can link you up with our Twilio account manager.

If you don't receive your test SMS, it is likely that this Sender ID has been taken by another agency. You should use the Alphanumeric Sender ID that you have registered with SGNIC in this field.

Send a message on Postman

Once you have successfully sent a test message on Twilio, you will be able to start sending messages on Postman.

Do ensure that you have completed configuration correctly before reattempting to send messages via Postman

What is this feature about?

This feature enables agencies to send messages to recipients using their NRIC instead of phone numbers, supporting the transition from Notify to Postman. Previously, some agencies relied on Notify for message delivery when they only had access to recipients' NRICs.

Authorised users can make API calls to Postman by providing the recipient's NRIC. The system will retrieve the associated phone number and deliver the message to the recipient. Users can expect the same experience they had with Notify.

This feature is exclusively available for authorised users, only through the Postman API.

Does this guarantee my messages will be sent to the recipient, as long as I have their NRIC?

No.

If the recipient does not have a phone number mapped to his/her NRIC in Singpass, no messages will be sent to the recipient even if you have their NRIC.

Release Schedule

Test Environment

The API specifications and feature will be available in Postman's test environment after April 20, 2025.

Production Environment

The target release date is June 2025, subject to potential delays.

Is there anything I will need to do before the release of this feature

Existing Notify users should have already received an email containing specific instructions and a form. You must complete this form before accessing the new feature in Postman's test environment.

What this does?

In Postman's test database, we will create a simulated database mapping unique identifiers to mobile numbers. These unique identifiers are designed to simulate NRIC-to-mobile number mapping, but they are not actual NRIC numbers.

When a form is submitted, Postman will assign a unique identifier to each submitted phone number in our test environment. Once this process is complete, we will inform agencies of the mapping.

When you make an API request using one of these unique identifiers, we will send a message to the corresponding phone number.

However, when calling our endpoints with a real NRIC, no message will be sent, as the test environment does not have real NRIC data; users should only call the unique identifier provided to them.

Attributes (sending SMSes using NRIC)

recipient (send smses using nric, mandatory)

To trigger a message to be sent to a mobile number when the recipient’s NRIC is provided, you will need to make some changes to the recipient attribute

Endpoints (sending SMSes using NRIC)

The following diagram illustrates how the message is created on Postman and sent to recipients.

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.

{
  "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 (Mandatory field)

Recipient is a mandatory field.

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)

Sending SMSes using NRIC

For users sending SMSes using NRIC, the recipient will comprise of value and type .

eg. the recipient field of the endpoint should be the following if users are sending SMSes using NRIC.

"recipient": {
	  "value": "S1234567A",
	  "type": "nric"
	  },

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

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.