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

NameInTypeDescription
fromqueryDateFirst date, YYYY-MM-DD, within the last 30 days. Default: first date of the window. example 2026-11-01
toqueryDateLast 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
instsquerystringComma-separated institution slugs from /v1/institutions. A message matches if it is from any of them. An unknown slug returns 404. example nubank,itau
channelsquerystringComma-separated channels: push, sms, email, inapp, whatsapp, fisica (physical mail). example push,email
tagsquerystringComma-separated tag ids from /v1/tags. A message matches if it has any of them. example 3f2a9c0e5b7d4e1f8a6c2b9d0e4f7a1c
productqueryintegerProduct id from /v1/products (main or extra product of the message). example 42
transactionalquerystring1 only transactional messages, 0 only non-transactional. one of "0", "1"
qquerystringFull-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
viewquerystringcard (default, compact, saves tokens) or full. Both count the same against the budget. one of "card", "full" · default "card"
limitqueryintegerPage size, 1 to 50. minimum 1 · maximum 50 · default 50
cursorquerystringnext_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-newintegerDistinct 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-remainingintegerDistinct messages left in this month's budget, after this response. Sent on every response once your client is identified.
x-request-idstringRequest id. Quote it when contacting support.

Body application/json

Schema: MessageList

FieldTypeDescription
dataarray of Card | FullMessageCards (view=card) or full messages (view=full).
next_cursorstring | nullPass as cursor to get the next page; null when there are no more.
as_ofDate

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

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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-afterintegerSeconds to wait before retrying.
x-request-idstringRequest id. Quote it when contacting support.

Body application/json

Schema: Error

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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-idstringRequest id. Quote it when contacting support.

Body application/json

Schema: Error

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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-afterintegerSeconds to wait before retrying.
x-request-idstringRequest id. Quote it when contacting support.

Body application/json

Schema: Error

FieldTypeDescription
errorstring one of "bad_request", "window", "bad_cursor", "forbidden", "disabled", "access_ended", "not_found", "method_not_allowed", "rate_limited", "internal"
messagestringWhat happened and what to do, in English.
detail optionalanyExtra 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."
}