Brand key required
Messages
One conversation per creator. Sending delivers in-app and by email; the creator's reply lands back in the same thread. The list endpoint carries previews only. Fetch the thread by ID for full text.
List conversations
GET/v1/messages
| Parameter | Type | Description |
|---|---|---|
| unread | boolean | unread=true returns only conversations with messages you have not read. |
| page / limit | integer | Standard pagination. |
request
curl "https://api.ugcroster.com/v1/messages?unread=true" \
-H "Authorization: Bearer rsk_brand_key"response 200
{
"data": [
{
"id": "conv_001",
"creator_email": "emma@example.com",
"creator_name": "Emma Chen",
"creator_user_id": "user_123",
"form_id": "form_xyz789",
"form_title": "Summer Skincare Launch",
"last_message": "Just posted the reel! Check it out.",
"last_sender_type": "creator",
"last_message_at": "2026-06-13T11:00:00Z",
"unread_by_brand": 1,
"created_at": "2026-05-22T09:00:00Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 28, "has_more": true }
}last_message is a preview truncated to 200 characters. Never parse it as the message. Read the thread instead.
Send a message
POST/v1/messages
| Field | Type | Description |
|---|---|---|
| creator_email | string | Required. Finds or creates the conversation for this creator. |
| body | string | Required. The message text. (The field is body, not message.) |
| subject | string | Email subject line; also stored as the conversation title for new conversations. |
| creator_name | string | Optional display name for a brand-initiated conversation. |
| instagram_handle | string | Optional handle for a brand-initiated conversation; enriched from the creator directory when omitted. |
request
curl -X POST "https://api.ugcroster.com/v1/messages" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{
"creator_email": "emma@example.com",
"subject": "Great work on the reel!",
"body": "Hi Emma, the reel looks amazing. Can you also create a story version?"
}'response 200
{ "data": { "conversation_id": "conv_001" } }The creator is emailed a notification with your brand’s contact email as reply-to, and the message appears in their Roster inbox.
Read a thread
GET/v1/messages/{id}
| Parameter | Type | Description |
|---|---|---|
| id | string (path) | Conversation ID from the list endpoint (or from a send response). |
| limit | integer | Number of most-recent messages to return. Default 50, max 200. |
request
curl "https://api.ugcroster.com/v1/messages/conv_001?limit=100" \
-H "Authorization: Bearer rsk_brand_key"response 200
{
"data": {
"id": "conv_001",
"creator_email": "emma@example.com",
"creator_name": "Emma Chen",
"creator_user_id": "user_123",
"form_id": "form_xyz789",
"form_title": "Summer Skincare Launch",
"last_message_at": "2026-06-13T11:00:00Z",
"created_at": "2026-05-22T09:00:00Z",
"messages": [
{
"id": "msg_014",
"sender_type": "brand",
"sender_name": "Glow Skincare",
"sender_email": "sarah@glowskincare.com",
"body": "Hi Emma, the reel looks amazing.",
"created_at": "2026-06-13T10:40:00Z"
},
{
"id": "msg_015",
"sender_type": "creator",
"sender_name": "Emma Chen",
"sender_email": "emma@example.com",
"body": "Just posted the reel! Check it out.",
"created_at": "2026-06-13T11:00:00Z"
}
]
}
}Messages are returned oldest-first within the returned window.