messages
Search messages by filters and text
GET/v1/messages
Messages in the window matching all given filters, ordered by date descending, then institution and seq. Default range: the whole window.
Authentication: CF-Access-Client-Id + CF-Access-Client-Secret. Operation id searchMessages.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | Date | First date, YYYY-MM-DD, within the last 30 days. Default: first date of the window. example 2026-11-01 |
to | query | Date | Last date, YYYY-MM-DD. Default: today (Brasília). A date after today is treated as today. from after to returns an empty list. example 2026-11-08 |
insts | query | string | Comma-separated institution slugs from /v1/institutions. A message matches if it is from any of them. An unknown slug returns 404. example nubank,itau |
channels | query | string | Comma-separated channels: push, sms, email, inapp, whatsapp, fisica (physical mail). example push,email |
tags | query | string | Comma-separated tag ids from /v1/tags. A message matches if it has any of them. example 3f2a9c0e5b7d4e1f8a6c2b9d0e4f7a1c |
product | query | integer | Product id from /v1/products (main or extra product of the message). example 42 |
transactional | query | string | 1 only transactional messages, 0 only non-transactional. one of "0", "1" |
q | query | string | Full-text search over title, summary and content text. Plain words, case- and accent-insensitive; all words must match. Up to 200 characters and 12 words. maxLength 200example cashback pix |
view | query | string | card (default, compact, saves tokens) or full. Both count the same against the budget. one of "card", "full" · default "card" |
limit | query | integer | Page size, 1 to 50. minimum 1 · maximum 50 · default 50 |
cursor | query | string | next_cursor from the previous page. Send it with the same filters and dates (limit and view may change). Valid for 1 hour, bound to your credential, to the filters and to the dates they resolved to: with a default since/from, a day change in Brasília invalidates it (400 bad_cursor; restart without cursor). |
Request example
Shell
curl -s https://api.mint.xcorp.cc/v1/messages \
-H "CF-Access-Client-Id: $MINT_ID" \
-H "CF-Access-Client-Secret: $MINT_SECRET"Responses
200A page of messages. MessageList
Headers
x-records-new | integer | Distinct messages in this response charged now (first delivery this month). Sent on every response once your client is identified; 0 on routes that do not charge. |
x-budget-remaining | integer | Distinct messages left in this month's budget, after this response. Sent on every response once your client is identified. |
x-request-id | string | Request id. Quote it when contacting support. |
Body application/json
Schema: MessageList
| Field | Type | Description |
|---|---|---|
data | array of Card | FullMessage | Cards (view=card) or full messages (view=full). |
next_cursor | string | null | Pass as cursor to get the next page; null when there are no more. |
as_of | Date |
Example: A page of cards (view=card)
JSON
{
"data": [
{
"id": "9b1e4c7a2d5f8e0b3a6c9d2e5f8a1b4c",
"institution": "nubank",
"date": "2026-11-08",
"seq": 3,
"title": "Ganhe cashback no Pix no crédito",
"channel": "push",
"tags": [
"Cashback",
"Pix"
],
"summary": "Offers 2% cashback on Pix paid with the credit card until month end."
}
],
"next_cursor": null,
"as_of": "2026-11-08"
}400Invalid, unknown or repeated parameter (bad_request, with detail = {param, why}), date before the window (window, first accepted date in detail.first_date) or invalid cursor (bad_cursor: tampered, expired, from another credential, other filters or another day; restart without cursor). BadRequest
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "window",
"message": "Dates before 2026-10-09 are outside the 30-day window. Use since/from on or after that date; for older trends use /v1/stats.",
"detail": {
"first_date": "2026-10-09"
}
}403No valid credential (forbidden), access disabled (disabled) or access period over (access_ended). Do not retry; contact XCORP. Forbidden
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "access_ended",
"message": "Your access period has ended. Contact XCORP."
}404Message does not exist, is outside the window or is not visible to you; or an unknown institution, tag or product in a filter. All these cases look the same. NotFound
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "not_found",
"message": "Not found. Messages exist here only for the last 30 days; check ids and slugs against the catalogs."
}405Only GET is allowed (HEAD and OPTIONS too return 405). MethodNotAllowed
Headers
allow | "GET" | Allowed methods: GET. |
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "method_not_allowed",
"message": "This API is read-only. Use GET."
}429A limit of your access plan was reached. detail.limit is minute (requests per minute), day (requests per day), images (images per day) or budget (distinct messages per month). Wait retry-after seconds. Your limits: /v1/usage. RateLimited
Headers
retry-after | integer | Seconds to wait before retrying. |
x-request-id | string | Request id. Quote it when contacting support. |
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "rate_limited",
"message": "Too many requests per minute. Wait for retry-after seconds, then continue.",
"detail": {
"limit": "minute"
}
}500Unexpected error (internal). Retry later; quote x-request-id to support. Internal
Headers
x-request-id | string | Request id. Quote it when contacting support. |
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "internal",
"message": "Unexpected error. Retry later and quote x-request-id if it persists."
}503Service temporarily disabled for all clients (disabled). Retry after retry-after seconds. Disabled
Headers
retry-after | integer | Seconds to wait before retrying. |
x-request-id | string | Request id. Quote it when contacting support. |
Body application/json
Schema: Error
| Field | Type | Description |
|---|---|---|
error | string | one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal" |
message | string | What happened and what to do, in English. |
detail optional | any | Extra information: {"param", "why"} for every bad_request, {"first_date"} for window, {"limit"} for rate_limited. |
Example
JSON
{
"error": "disabled",
"message": "The service is temporarily disabled. Try again later."
}