Postman Guide
Go to Postman v1
  • 🥳About Postman v1 (Postman Legacy)
  • Campaign Guide - General
    • 🚀How to send a campaign?
      • ☝️Before You Start
        • Demo Mode
  • Campaign Guide - Email
    • 📧Email Campaigns - Basics
      • How do I send an email campaign?
      • Scheduled Sending
      • Bounced Emails and Halted Campaigns
      • Email Statistics
      • Formatting your Message Template
      • Variable Fields
      • Unique URL Link per Recipient
      • Pasting Content from Microsoft Word
      • Manage your Unsubscriptions
      • Understanding Unsubscriptions
    • 🔐Sending Password-Protected Emails
      • Tutorial
      • Template Editor
  • Campaign Guide - SMS
    • 📲SMS Campaigns - Basics
      • Before Starting Out
      • Summary of Costs
    • 🪜SMS Onboarding Overview
      • Step 1: Sender ID Registration
      • Step 2: Sign up for a Twilio account
      • Step 3: Set up your Twilio account
      • Step 4: Configure Your Twilio Account
        • What if I need to buy a phone number?
      • Step 5: Send a Test Message on Twilio
      • Step 6: Fill in your Twilio credentials in Postman!
        • How do I send a campaign with my saved SMS credentials?
    • 🤔What else do I need to know about sending SMSes?
      • More about Sender ID registration
      • Can I see the send status of my campaign?
      • How can I configure my SMS send rate?
      • Sending an SMS to a Foreign Number
      • SMS Best Practices
      • Useful Twilio Links
  • Campaign Guide - Telegram
    • 🤖Telegram Campaigns - Basics
      • How do I set up Telegram to send my campaigns?
      • Add Telegram Bot Token in Postman
      • Instructions for Recipient Onboarding
      • Use the Bot in the Campaign
      • Telegram Formatting
      • Telegram Bot Statistics
  • Email API Guide
    • 📖Overview
      • IM8 Policies
      • Connecting your Intranet Application
      • API Response Formats
    • 🗝️Email API Key Management
      • Bearer Authentication
      • Generate your email API Key
      • Rotate your email API Key
    • 📨Programmatic Email API
      • Getting Started
      • Comparison with AMR
      • SG-Mail Whitelisting
      • Custom From Address
      • Tracking Email Status
      • Send Email API
        • From Name and From Address
        • CC and BCC
        • Recipient Blacklist
        • Email Tagging and Classification
        • Email Body
          • Embedding Images
            • Linked Images
            • Content-ID Images
        • Attachments
        • Rate Limit
      • Get Email by ID API
      • List Emails API
    • 📨Programmatic GovSG WhatsApp API
      • Getting Started
      • Tracking Message Status
      • Get Available Templates API
      • Send Message API
      • Get Message by ID API
      • List Messages API
    • 🎓Frequently Asked Questions
  • FAQ
    • 📶Service Status
    • For Recipients
      • Check Email Authenticity
    • For Senders
      • Messaging Channel Comparison
      • Cost Breakdown
  • Legal
    • Terms & Conditions
    • Privacy Policy
  • Contact Us
  • GitHub
Powered by GitBook
On this page
  • Request body for listing transactional emails
  • Query Parameters
  • Response body for listing emails API
  • Excluding params Field from Response

Was this helpful?

  1. Email API Guide
  2. Programmatic Email API

List Emails API

This API allows you to retrieve previously sent emails.

GET /v1/transactional/email

The above returns the first 10 emails sorted by created_at in descending order

Request body for listing transactional emails

eg. Response Body
const response = await fetch('/v1/transactional/email', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Query Parameters

limit integer

max number of messages returned


offset integer

offset to begin returning messages from

`offset` endpoint example
GET /transactional/email?limit=20&offset=10

The example above returns the next 20 emails sorted by created_at in descending order


status array of enums

status of messages to filter for.

item enum

  • UNSENT

  • ACCEPTED

  • SENT

  • BOUNCED

  • DELIVERED

  • OPENED

  • COMPLAINT

`delivered` status example
GET /transactional/email?status=DELIVERED

The example above returns the first 10 emails with the status delivered, soered by created_at in descending order.


created_at object

Filter for created_at timestamp of messages that corresponds to the time the API call to send the email was made.

Operators
Explanation

gt

greater than

gte

greater than or equal to

lt

less than

lte

less than or equal to

`get` status time example
GET /transactional/email?created_at[gt]=2023-05-10T03:03:54.163Z

The example above returns the first 10 emails created after 2023-05-10T03:03:54.163Z ,sorted by created_at in descending order. Do note that if the timezone is not specified, it will be assumed to be UTC.

`get` status example
GET /transactional/email?created_at[gt]=2023-05-03&created_at[lt]=2023-05-10

Returns the first 10 emails created between 2023-05-03 and 2023-05-10 sorted by created_at in descending order.


sort_by array of enum

The default sorting option is created_at, descending.

We currently support the following sorting options:

  • created_at: sort by the time when the email was created; this roughly corresponds to the time when the API call to send the email was made

  • updated_at: sort by the time when the email was last updated

We support both ascending and descending order.

To specify the order, add the prefix + for ascending order and - for descending order.

For example, +created_at will sort by created_at in ascending order, and -updated_at will sort by updated_at in descending order. If the prefix is omitted, descending order will be used.

`sorted_by` example
GET /transactional/email?sort_by=+created_at&created_at[gte]=2022-11-01&status=delivered&limit=48

Returns the first 48 emails with status DELIVERED created on or after 2022-11-01 sorted by created_at in ascending order.


Response body for listing emails API

Listing emails API response example
{
  "has_more": false,
  "data": [
    {
      "id": 42,
      "from": "Postman <info@mail.postman.gov.sg>",
      "recipient": "hello@example.com",
      "params": {
        "body": "Hello World",
        "from": "Postman <info@mail.postman.gov.sg>",
        "subject": "Hello World",
        "reply_to": "hello@example.com"
      },
      "attachments_metadata": [
        {
          "fileName": "text",
          "fileSize": 0,
          "hash": "text"
        }
      ],
      "status": "UNSENT",
      "error_code": "text",
      "error_sub_type": "text",
      "created_at": "2024-09-02T01:34:37.342Z",
      "updated_at": "2024-09-02T01:34:37.342Z",
      "accepted_at": "2024-09-02T01:34:37.342Z",
      "sent_at": "2024-09-02T01:34:37.342Z",
      "delivered_at": "2024-09-02T01:34:37.342Z",
      "opened_at": "2024-09-02T01:34:37.342Z"
    }
  ]

The response is a JSON object with the following fields:

  • has_more: a boolean indicating whether there are more emails to retrieve

Excluding params Field from Response

Depending on the email body, the params field could be fairly large and unnecessary to users who are calling this API to retrieve the latest status.

As such, we support an optional exclude_params field that allows you to exclude the params field from the response. To do so, set exclude_params to true in the query parameters, i.e. GET /transactional/email?exclude_params=true. If exclude_params is not specified, the params field will be included in the response.

PreviousGet Email by ID APINextProgrammatic GovSG WhatsApp API

Last updated 8 months ago

Was this helpful?

This return emails with the specified status. For a list of possible values, see

For created_at, the timestamp should be specified in valid . The list of supported operators are:

data: an array of JSON email objects. You can find an example of a single JSON email object . We support excluding the params field from the response object, see for more information.

📨
this section
ISO 8601 format
this section
here