MyGrainExchange

Messages

Every bid on MGX comes with a conversation. These endpoints let your product carry that conversation — a grower can answer a buyer's question about protein or delivery without leaving your app. Or frame the Messages embed and skip building it.

messages.read and messages.write are granted to approved partners, not self-service. A thread is a direct line to a counterparty, so contact MGX to have them enabled on your API client.

Threads are addressed by their reference — CHT-26G-0015 — not by an internal id. Use it wherever a thread id is asked for.

Who is who

This is the part to read carefully. MGX's rule is that neither side of a deal learns the other's identity until the deal is done, and these endpoints hold that line:

  • Before settlement, the counterparty is a generic "Buyer" or "Seller". No name, no company, no email.
  • A verified elevator is named even before settlement — its storefront is already public on MGX, so naming it reveals nothing new. You'll see is_elevator: true.
  • After both invoices on the trade are paid, settled flips to true and real names and companies appear.

Every party — on a thread, on a message — is described the same way, so the list and the thread never disagree:

{ "label": "Seller", "company": null, "is_elevator": false }

Your own messages come back with mine: true and a "You" label, so you never have to work out which side of the thread to render them on.

Moderation

Messages pass the same moderation the MGX app applies. A message you send may come back with moderation_status: "pending" — it is stored, it is visible to its author, and it does not reach the counterparty until it is approved. Render pending messages as sent-but-unconfirmed rather than hiding them; the author should see what they wrote.

Reading a thread only ever returns other people's messages once approved.

GET/v1/me/messages

List threads

Threads the user is a participant in, most recent first. Requires messages.read.

  • Name
    unread
    Type
    boolean
    Description

    Only threads with unread messages.

  • Name
    limit
    Type
    integer
    Description

    Page size. Defaults to 20, max 50.

  • Name
    offset
    Type
    integer
    Description

    Page offset.

Request

GET
/v1/me/messages
curl https://api.mygrainexchange.com/v1/me/messages \
  -H "Authorization: Bearer {token}"
GET/v1/me/messages/:reference

Read a thread

One thread and its messages, oldest first. Reading marks the thread as seen, the same as opening it in MGX — so don't poll this endpoint to check for new messages; use the list and its unread flag.

A thread the user is not a participant in returns 404, never 403: membership is the authorization, and a caller learns nothing about threads that aren't theirs.

Request

GET
/v1/me/messages/CHT-26G-0015
curl https://api.mygrainexchange.com/v1/me/messages/CHT-26G-0015 \
  -H "Authorization: Bearer {token}"
POST/v1/me/messages/:reference

Send a message

Post into an existing thread. Requires messages.write.

There is no endpoint here for starting a thread: threads open when a bid is placed, so the conversation always has a deal attached to it.

  • Name
    body
    Type
    string
    Description

    The message. 1–2000 characters (required).

Request

POST
/v1/me/messages/CHT-26G-0015
curl -X POST https://api.mygrainexchange.com/v1/me/messages/CHT-26G-0015 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "body": "34 works. I can load Tuesday." }'

Was this page helpful?