SES Monitor Messages API

The SES Monitor API's Messages Endpoint is a powerful tool that allows you to retrieve detailed information about your email messages. This endpoint accepts several query parameters that enable you to filter and refine your search. Here's a guide on using these parameters effectively.

See also: Authenticating with the SES Monitor API

Query Parameters

uuid (Unique Identifier)

• Description: This is the unique UUID of the message.
• Format: A string representing the UUID.
• Usage: To retrieve information about a specific email message.

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"uuid": "768c5f24-beca-11ee-ad68-b21dbfe5a9e7"}}'

domain_uuid (Domain Identifier)

• Description: The UUID of the sender domain attached to the message.
• Format: A string representing the UUID of the domain.
• Usage: To filter messages sent from a specific domain.

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"uuid": "768c5f24-beca-11ee-ad68-b21dbfe5a9e7"}}'

mailer_timestamp_gte (Greater Than or Equal)

• Description: Filters messages sent on or after a specific date and time.
• Format: Date/Time in the format "YYYY-MM-DD HH:MM:SS".
• Usage: To find messages sent after a certain date and time.

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"mailer_timestamp_gte": "2024-01-01 00:00:00"}}'

mailer_timestamp_lte (Less Than or Equal)

• Description: Filters messages sent on or before a specific date and time.
• Format: Date/Time in the format "YYYY-MM-DD HH:MM:SS".
• Usage: To find messages sent before a certain date and time.

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"mailer_timestamp_lte": "2024-01-31 23:59:59"}}'

did_bounce (boolean)

• Description: Only return messages that have at least one bounce event
• Format: boolean: true / false

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"did_bounce": true}}'

did_complain (boolean)

• Description: Only return messages that have at least one complaint event
• Format: boolean: true / false

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"did_complain": true}}'

did_deliver (boolean)

• Description: Only return messages that have at least one delivery
• Format: boolean: true / false

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"did_deliver": true}}'

did_open (boolean)

• Description: Only return messages that have at least one open event
• Format: boolean: true / false

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"did_open": true}}'

did_click (boolean)

• Description: Only return messages that have at least one click event
• Format: boolean: true / false

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{"query": {"did_click": true}}'

Message Pagination

To manage large sets of data efficiently, the SES Monitor API's Messages Endpoint supports pagination. This feature allows you to retrieve your data in manageable chunks or "pages". Here's how you can utilize pagination in your API requests.

page

• Description: Specifies the page number of the results.
• Format: An integer.
• Usage: To navigate through multiple pages of results.

per_page

• Description: Determines the number of results per page.
• Default: 25 results per page.
• Maximum: Can be set up to 100 results per page.
• Format: An integer.
• Usage: To adjust the number of results returned in a single request.

To implement pagination in your request, you'll need to include the page and per_page fields in your POST data. Here's an example using CURL:

curl -X POST 'https://api.sesmonitor.com/api/v1/messages/list' \
-H 'Authorization: Bearer YOUR_API_ACCESS_KEY' \
-H 'Content-Type: application/json' \
-d '{
      "query": {
        "mailer_timestamp_gte": "2024-01-01 00:00:00",
        "mailer_timestamp_lte": "2024-01-31 23:59:59"
      },
      "page": 2,
      "per_page": 50
    }'

In the above example the request retrieves messages sent between January 1, 2024, and January 31, 2024. It requests the second page of results with 50 messages per page (instead of the default 25).