Messages

GET /conversations

Conversations

Scope: messages:read, or the broad read. Newest first, by id.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/conversations" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

{
    "data": [
        {
            "id": 1024,
            "subject": "A question",
            "sender_id": 1024,
            "recipient_id": 1024,
            "created_at": "2026-10-10T14:03:22Z",
            "last_message_at": "2026-10-10T14:03:22Z",
            "open": true,
            "unread": true,
            "archived": true,
            "important": true
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /conversations

Start a conversation with one member, or the same message with several

Scope: messages:write, or the broad write. Idempotency-Key is required.

The website's own sending rules apply. The recipient is emailed after the message is stored. With recipient_ids the same message starts a thread with each member (MessagesCreated); every recipient is checked first, and if any cannot be messaged nothing is sent and errors.recipient_ids names the first who cannot.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/conversations" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: createconversation-1" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":77,"subject":"Question about your logo service","message":"Can you deliver in two days?"}'

Response 201

{
    "data": {
        "conversation_id": 55120,
        "message_id": 990134
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

GET /conversations/folders

Inbox folders

Scope: messages:read, or the broad read. Newest first, by id.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/conversations/folders" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

{
    "data": [
        {
            "id": 1024,
            "name": "Example",
            "color": "blue",
            "created_at": "2026-10-10T14:03:22Z"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /conversations/folders

Make an inbox folder

Scope: messages:write, or the broad write. Idempotency-Key is required.

At most 16 folders, as the website's inbox allows. Tags are removed from the name and it is stored HTML-encoded, as the website stores it; reads give it encoded.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/conversations/folders" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: createinboxfolder-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}'

Response 201

{
    "data": {
        "id": 1024,
        "name": "Example",
        "color": "blue",
        "created_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /conversations/folders/{id}

Colour an inbox folder

Scope: messages:write, or the broad write. Idempotency-Key is optional.

The colours the inbox's colour menu offers. The folder must be one of yours.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/conversations/folders/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color":"blue"}'

Response 200

{
    "data": {
        "id": 1024,
        "name": "Example",
        "color": "blue",
        "created_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

DELETE /conversations/folders/{id}

Delete an inbox folder

Scope: messages:write, or the broad write. Idempotency-Key is optional.

As on the website: the folder is hidden; its conversations are not touched.

Parameters

Example request

curl -X DELETE "https://www.seoclerk.com/api/v1/conversations/folders/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 204

No body.

Errors

POST /conversations/folders/{id}/conversations

Put a conversation in an inbox folder

Scope: messages:write, or the broad write. Idempotency-Key is required.

The folder must be yours and the conversation one you are in. One already there is left as it is.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/conversations/folders/1024/conversations" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: addconversationtofolder-1" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":1024}'

Response 204

No body.

Errors

DELETE /conversations/folders/{id}/conversations/{conversation_id}

Take a conversation out of an inbox folder

Scope: messages:write, or the broad write. Idempotency-Key is optional.

Parameters

Example request

curl -X DELETE "https://www.seoclerk.com/api/v1/conversations/folders/1024/conversations/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 204

No body.

Errors

GET /conversations/{id}

A conversation

Scope: messages:read, or the broad read. A participant; anyone else gets 404.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/conversations/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

{
    "data": {
        "id": 1024,
        "subject": "A question",
        "sender_id": 1024,
        "recipient_id": 1024,
        "created_at": "2026-10-10T14:03:22Z",
        "last_message_at": "2026-10-10T14:03:22Z",
        "open": true,
        "unread": true,
        "archived": true,
        "important": true
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /conversations/{id}

Set your unread, archived or important flag

Scope: messages:write, or the broad write. A participant; anyone else gets 404. Idempotency-Key is optional.

Only the caller's own flags.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/conversations/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'

Response 200

{
    "data": {
        "id": 55120,
        "unread": false,
        "archived": true,
        "important": false
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

GET /conversations/{id}/messages

A conversation's messages

Scope: messages:read, or the broad read. A participant; anyone else gets 404. Newest first, by id.

Reading marks nothing read.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/conversations/1024/messages" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

{
    "data": [
        {
            "id": 1024,
            "sender_id": 1024,
            "recipient_id": 1024,
            "text": "Hello.",
            "created_at": "2026-10-10T14:03:22Z",
            "attachment_id": 1024,
            "action": "string"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /conversations/{id}/messages

Reply to a conversation

Scope: messages:write, or the broad write. A participant; anyone else gets 404. Idempotency-Key is required.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/conversations/1024/messages" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: createconversationmessage-1" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello."}'

Response 201

{
    "data": {
        "conversation_id": 1024,
        "message_id": 1024
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /conversations/{id}/messages/{message_id}

Edit your own message

Scope: messages:write, or the broad write. The message's sender. Idempotency-Key is optional.

Changes the text only; an attachment stays as it is.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/conversations/1024/messages/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello."}'

Response 200

{
    "data": {
        "id": 1024,
        "sender_id": 1024,
        "recipient_id": 1024,
        "text": "Hello.",
        "created_at": "2026-10-10T14:03:22Z",
        "attachment_id": 1024,
        "action": "string"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors