# FAQs (API)

{% hint style="info" %}
**Still need help?**\
\&#xNAN;*Postman is a fully self-service platform however we understand there may be times where you would like to reach out to someone.*

* Kindly [reach out to your PICs](https://postman-v2.guides.gov.sg/general-users-ui-portal/request-for-campaign-creation-rights-from-agency-pics) first who will be able provide you with more agency specific context on Postman
* Should your PIC be unable to assist, you may [reach out to the Postman team](https://form.gov.sg/657025a2d2bd350012c82eb0). In our responses, we will also be cc-ing your PICs.
  {% endhint %}

### API Keys & Authentication

<details>

<summary><strong>How do I obtain my API keys?</strong></summary>

API keys are generated from the Postman Admin Portal. You will first need to:

1. Create a campaign and obtain a campaign ID
2. Whitelist your IP address
3. Generate your API keys

You can only obtain your API keys after you have whitelisted your IP address. Each campaign can have up to 3 API keys. For testing, you can obtain your API keys on [test.postman.gov.sg](https://test.postman.gov.sg).

</details>

<details>

<summary><strong>Do API keys expire?</strong></summary>

No, API keys have no expiry. If you need a new API key, you can delete the old key and generate a new one from the campaign settings.

</details>

<details>

<summary><strong>Does each agency get one API key, or can each system have its own?</strong></summary>

API keys are tied to each campaign, not to agencies. Each campaign can have up to 3 API keys. The number of keys depends on how many campaigns your agency has created.

</details>

<details>

<summary><strong>What authentication method does Postman use?</strong></summary>

Postman uses HTTP Bearer Auth. Include your API key in the `Authorization` header of every request:

```
Authorization: Bearer YOUR_API_KEY
```

All API calls must be made over HTTPS. Calls over plain HTTP will fail, and requests without authentication will return HTTP 401.

</details>

### IP Address Whitelisting

<details>

<summary><strong>What type of IP addresses can I whitelist?</strong></summary>

You must whitelist static public IP addresses. These must be the IP addresses you are using to call the Postman API. If you are connecting via VPN, whitelist the VPN's public IP address.

</details>

<details>

<summary><strong>How many IP addresses can I whitelist?</strong></summary>

You can whitelist up to 20 IP addresses per campaign on the admin portal.

</details>

<details>

<summary><strong>Does Postman accept CIDR blocks?</strong></summary>

No, you need to whitelist individual IP addresses. Bulk upload is also not supported; you will need to add them one at a time.

</details>

<details>

<summary><strong>What is Postman's IP address?</strong></summary>

We do not provide our IP address. You can whitelist our domain name instead. If you really need the IP address, you can resolve the domain to find it, but you will be responsible for updating it if it changes.

</details>

<details>

<summary><strong>Do I need to open any firewall rules?</strong></summary>

You will need to whitelist your IP addresses with us before you can obtain your API keys. There are no additional firewall rules required on Postman's side. Whitelisting the source IP address is sufficient for you to use Postman to send SMSes.

</details>

### Sending Messages

<details>

<summary><strong>Should I use Single Send or Batch Send?</strong></summary>

Use **Single Send** for time-sensitive, critical SMSes like OTPs or weather alerts. OTP messages via Single Send are given the highest priority in the message queue.\
\
Use **Batch Send** for sending to multiple recipients in a single API call via CSV upload. Batch send messages are given lower priority than single send messages.\
\
For single send, 1 TPS = 1 API call = 1 message. For batch send, 1 TPS = 1 API call = multiple messages (one per row in the CSV).

</details>

<details>

<summary><strong>How do I add line breaks in my single send API request?</strong></summary>

Add `\n` into the JSON request body. Make sure your request body is in valid JSON format.

```json
{
  "recipient": "6599999999",
  "language": "english",
  "values": {
    "body": "Dear John,\n\nYour appointment is confirmed.\n\nPlease do not reply."
  }
}
```

For batch send CSV files, use keyboard line breaks directly within the CSV cell instead of `\n`.

</details>

<details>

<summary><strong>Where do I find my campaign ID?</strong></summary>

Your campaign ID is generated when you create a campaign on the Postman admin portal. You can find it in the campaign settings page. Refer to our API documents for more information.

</details>

### Message Status & Delivery

<details>

<summary><strong>How do I check if my message was delivered?</strong></summary>

The response from the Single Send or Batch Send endpoint only confirms the message was created. You must poll the Retrieve Message or Retrieve Batch endpoint to get the `latestStatus`.\
\
Webhooks for delivery status updates are not currently supported.

</details>

<details>

<summary><strong>How long does it take for a message to be delivered?</strong></summary>

Postman does not publish specific SLAs on delivery timing. The time taken depends on system load at the point of sending. Message delivery speeds may be slower during peak periods (8:00 am to 6:00 pm daily).

</details>

<details>

<summary><strong>Does Postman provide a webhook for delivery status updates?</strong></summary>

No, webhooks are not currently supported. You must poll the Retrieve Message or Retrieve Batch endpoint to check for status changes.

</details>

<details>

<summary><strong>Will Postman automatically retry failed messages?</strong></summary>

No. You must manually retry failed messages using the Single Send - Retry or Batch Send - Retry endpoint. Each message can be retried up to 3 times.

</details>

<details>

<summary><strong>What does the status <code>sent_to_telco</code> mean? Is the message delivered?</strong></summary>

`sent_to_telco` means the messaging service provider has sent the message to the recipient's telco, but it may or may not have been delivered to the recipient's phone (e.g. the phone could be off or in airplane mode).\
\
If the status remains `sent_to_telco` beyond 48 hours, it is unlikely that a further update will be received. This is a telco limitation. You may compose a new message if needed, though there is a possibility of the recipient receiving the same message twice.

</details>

### Rate Limits & Errors

<details>

<summary><strong>What is the default rate limit?</strong></summary>

The default rate limit is 10 TPS (transactions per second) per campaign ID. This is the number of API calls per second, not the number of messages. The rate limit is shared across all API endpoints for a campaign.\
\
For example, if you call Single Send at 6 TPS, Retrieve Message at 2 TPS, and Batch Send at 4 TPS simultaneously, that totals 12 TPS and you will hit the rate limit.

</details>

<details>

<summary><strong>How do I request a higher TPS?</strong></summary>

Submit a request via the [contact form](https://form.gov.sg/6130d7708f80b00012ae8eac) with your use case and ideal TPS. We require evidence of historical usage (not from Postman test logs).

</details>

<details>

<summary><strong>For 5xx server errors, will my requests be queued?</strong></summary>

No. Requests are not queued on Postman's side for 5xx errors. You will need to retry these requests yourself. Implement exponential backoff in your retry logic.

</details>

<details>

<summary><strong>What happens when I hit the rate limit?</strong></summary>

Postman will drop the request and return `HTTP 429 Too Many Requests`. Dropped requests are not queued. You are responsible for implementing retry mechanisms (e.g. exponential backoff). Your campaign's TPS will not be increased because you hit the rate limit.

</details>

### Vendor Access

<details>

<summary><strong>I am a vendor helping a government agency with API integration. How do I get access?</strong></summary>

Postman does not grant portal access to vendors with non-whitelisted email domains. The agency officer should:\
\
1\. Log into Postman and create the campaign\
2\. Craft the message template\
3\. Whitelist the vendor's IP addresses\
4\. Generate the API keys and pass them to the vendor\
\
Vendors will use the API keys provided by the agency for integration. If you have questions about the API, include the contact details of the government officer-in-charge and their agency email address in your [form response](https://form.gov.sg/657025a2d2bd350012c82eb0).

</details>

### Testing

<details>

<summary><strong>Where can I test the Postman API?</strong></summary>

Use the test environment at [test.postman.gov.sg](https://test.postman.gov.sg) for functional integration testing. The test environment API base URL is:\
\
`https://test.postman.gov.sg/api/v2`\
\
Do not use the production environment for testing. Non-compliance will be reported to your agency's CIO.\
\
The test site has a CSV file limit of 20 rows. Do not conduct load testing on the test site. Use the [load test environment](https://loadtest.postman.gov.sg) instead.

</details>

<details>

<summary><strong>Do I need to conduct a load test before going to production?</strong></summary>

Load testing is optional. Postman meets internal load test standards and has successfully supported multiple nationwide campaigns. If you do wish to load test, you must use the dedicated [load test environment](https://loadtest.postman.gov.sg) and [book a time slot](https://cal.gov.sg/n2g21zn65d6nr2pd80cd051p) at least five day in advance.

</details>

<details>

<summary><strong>Are messages sent in the test environment charged?</strong></summary>

No, messages sent in the test environment are not charged. These messages are for testing purposes only and cannot be sent to members of the public.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://postman-v2.guides.gov.sg/technical-users-api/faqs-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.