Messages

18 endpoints

Email message operations (fetch, send, update, delete)

GET /accounts/{accountId}/messages

Fetch messages from account

Get a paginated list of messages from a specific email account

Parameters

accountId string

In path • Required

Unique account identifier assigned by Riposte.

                        acct_123456789
                      

Additional parameters

page string

In query • Optional

1-indexed page number to return when using offset pagination.

                            1
                          

limit string

In query • Optional

Maximum number of messages to include in each page.

                            50
                          

labelId string

In query • Optional

Filter the list to messages with a specific label.

                            lbl_support
                          

mailbox string

In query • Optional

For IMAP accounts, select a specific mailbox/folder to read from.

                            INBOX
                          

maxResults string

In query • Optional

Deprecated legacy field, prefer limit.

                            100
                          

cursor string

In query • Optional

Cursor identifier returned from a previous response for deep pagination.

                            cursor_2024-06-12T17:22:00Z
                          

Returns

Paginated collection of message resources.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/messages"
                  
              

Example response 200

              {
  "messages": [
    {
      "id": "msg_01HZY8AW50MP89C11DW00SHM3R",
      "accountId": "acct_123456789",
      "providerMessageId": "1790c6accc1a2a5f",
      "subject": "Riposte onboarding call"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
            

---

DELETE /accounts/{accountId}/messages/{messageId}

Delete a message

Permanently delete a message from the provider inbox.

Parameters

accountId string

In path • Required

messageId string

In path • Required

Returns

Default Response

Status: 204

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X DELETE "http://localhost:8080/accounts/{accountId}/messages/{messageId}"
                  
              

Example response 204

No example response available.

---

GET /accounts/{accountId}/messages/{messageId}

Get a single message with labels

Retrieve a specific message with all its labels and metadata

Parameters

accountId string

In path • Required

messageId string

In path • Required

Returns

Wrapper containing a fully hydrated message.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/messages/{messageId}"
                  
              

Example response 200

              {
  "message": {
    "accountId": "acct_123456789",
    "from": "[email protected]",
    "to": [
      "[email protected]"
    ],
    "subject": "Customer onboarding call",
    "body": "<p>Looking forward to tomorrow.</p>",
    "bodyText": "Looking forward to tomorrow.",
    "isHtml": true,
    "snippet": "Looking forward to tomorrow.",
    "threadId": "thd_01J0B16WSX8M8TE1F4KZ9VQ9ZB",
    "headers": {
      "Message-ID": "<[email protected]>"
    },
    "sizeEstimate": 12857,
    "attachments": [
      {
        "attachmentId": "att_01J0B1X5HF7M8ZQ2BR",
        "filename": "agenda.pdf",
        "mimeType": "application/pdf",
        "size": 52342
      }
    ],
    "receivedAt": "2024-06-18T21:05:00.000Z",
    "provider": "google",
    "labels": [
      {
        "id": "lbl_support",
        "name": "support",
        "displayName": "Support",
        "type": "LABEL",
        "color": "#0050b3",
        "isSystem": false,
        "isHidden": false
      },
      {
        "id": "lbl_priority",
        "name": "priority",
        "displayName": "Priority",
        "type": "LABEL",
        "color": "#ff9900",
        "isSystem": false,
        "isHidden": false
      }
    ]
  }
}
            

---

PUT /accounts/{accountId}/messages/{messageId}

Update a message (labels, read status, starred, etc.)

Update message properties like labels, read status, starred status, etc.

Parameters

accountId string

In path • Required

messageId string

In path • Required

Request body

Optional • application/json

Request body (application/json)

put-/accounts/{accountId}/messages/{messageId}-request-body-application/json

object<{ labelIds, isRead, isStarred, … }>

Field	Type	Description	Values
isRead Optional	boolean	—	—
isSpam Optional	boolean	—	—
isStarred Optional	boolean	—	—
isTrash Optional	boolean	—	—
labelIds Optional	array<string>	—	—

Returns

Generic success wrapper for endpoints that simply confirm completion.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X PUT "http://localhost:8080/accounts/{accountId}/messages/{messageId}" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

              {
  "success": true,
  "message": "Account paused successfully."
}
            

---

GET /accounts/{accountId}/messages/{messageId}/attachments

List attachments for a message

Get a list of all attachments for a specific message

Parameters

accountId string

In path • Required

messageId string

In path • Required

Returns

Default Response

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/messages/{messageId}/attachments"
                  
              

Example response 200

No example response available.

---

POST /accounts/{accountId}/messages/{messageId}/attachments

Upload attachment to message

Upload an attachment to an existing message or draft when supported by the provider.

Parameters

accountId string

In path • Required

messageId string

In path • Required

Request body

Required • application/json

Request body (application/json)

post-/accounts/{accountId}/messages/{messageId}/attachments-request-body-application/json

object<{ filename, mimeType, content, … }>

Field	Type	Description	Values
content Required	string	Base64 encoded content	—
contentId Optional	string	—	—
filename Required	string	—	—
inline Optional	boolean	—	—
mimeType Required	string	—	—

Returns

Response containing metadata about an uploaded attachment.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/accounts/{accountId}/messages/{messageId}/attachments" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

              {
  "attachment": {
    "attachmentId": "att_01J0B1X5HF7M8ZQ2BR",
    "filename": "agenda.pdf",
    "mimeType": "application/pdf",
    "size": 52342,
    "inline": false
  }
}
            

---

GET /accounts/{accountId}/messages/{messageId}/attachments/{attachmentId}

Download a message attachment

Download a specific attachment from a message

Parameters

accountId string

In path • Required

messageId string

In path • Required

attachmentId string

In path • Required

Returns

Default Response

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId}"
                  
              

Example response 200

No example response available.

---

POST /accounts/{accountId}/messages/{messageId}/forward

Forward a message

Forward an existing message to other recipients

Parameters

accountId string

In path • Required

messageId string

In path • Required

Request body

Required • application/json

Request body (application/json)

post-/accounts/{accountId}/messages/{messageId}/forward-request-body-application/json

object<{ to, cc, bcc, … }>

Field	Type	Description	Values
bcc Optional	array<string>	—	—
body Required	string	—	—
cc Optional	array<string>	—	—
forwardAsAttachment Optional	boolean	—	—
isHtml Optional	boolean	—	—
to Required	array<string>	—	—

Returns

Generic success wrapper for endpoints that simply confirm completion.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/accounts/{accountId}/messages/{messageId}/forward" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

              {
  "success": true,
  "message": "Account paused successfully."
}
            

---

GET /accounts/{accountId}/messages/{messageId}/raw

Get raw MIME message

Retrieve the full RFC822 MIME payload for a message.

Parameters

accountId string

In path • Required

messageId string

In path • Required

Returns

Full RFC822 MIME payload of an email message encoded as UTF-8 text.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/messages/{messageId}/raw"
                  
              

Example response 200

              From: [email protected]
To: [email protected]
Subject: Welcome
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"

Looking forward to working together.
            

---

POST /accounts/{accountId}/messages/{messageId}/reply

Reply to a message

Reply to an existing message

Parameters

accountId string

In path • Required

messageId string

In path • Required

Request body

Required • application/json

Request body (application/json)

post-/accounts/{accountId}/messages/{messageId}/reply-request-body-application/json

object<{ body, isHtml, replyAll }>

Field	Type	Description	Values
body Required	string	—	—
isHtml Optional	boolean	—	—
replyAll Optional	boolean	—	—

Returns

Response returned after replying to or forwarding a message.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/accounts/{accountId}/messages/{messageId}/reply" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

              {
  "success": true,
  "messageId": "msg_01J0B1Y0XWG7RP1KNQM"
}
            

---

GET /accounts/{accountId}/messages/search

Search messages

Search messages using advanced filters including subject, sender, recipients, and date ranges.

Parameters

accountId string

In path • Required

Additional parameters

query string

In query • Optional

subject string

In query • Optional

body string

In query • Optional

from string

In query • Optional

to string

In query • Optional

labelId string

In query • Optional

mailbox string

In query • Optional

date_from string (date-time)

In query • Optional

date_to string (date-time)

In query • Optional

page string

In query • Optional

limit string

In query • Optional

pageToken string

In query • Optional

Returns

Paginated collection of message resources.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/messages/search"
                  
              

Example response 200

              {
  "messages": [
    {
      "id": "msg_01HZY8AW50MP89C11DW00SHM3R",
      "accountId": "acct_123456789",
      "providerMessageId": "1790c6accc1a2a5f",
      "subject": "Riposte onboarding call"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
            

---

POST /accounts/{accountId}/send

Send message through account

Send an email message through the specified account

Parameters

accountId string

In path • Required

Unique account identifier assigned by Riposte.

                        acct_123456789
                      

Request body

Required • application/json

Simplified payload for sending a message using default account settings.

Request body (application/json)

post-/accounts/{accountId}/send-request-body-application/json

object<{ to, cc, bcc, … }>

Simplified payload for sending a message using default account settings.

Field	Type	Description	Values
bcc Optional	array<string>	Optional BCC recipients hidden from other recipients.	Example [ "[email protected]" ]
body Required	string	Message body formatted as either plain text or HTML. min length 1	Example Hi there, Thanks for signing up!
cc Optional	array<string>	Optional CC recipients.	Example [ "[email protected]" ]
isHtml Optional	boolean	Indicates whether the body content is HTML.	Example false
subject Required	string	Email subject line. min length 1	Example Welcome to Riposte
to Required	array<string>	Primary recipients for the message.	Example [ "[email protected]" ]

Returns

Response returned after sending or saving a message or draft.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/accounts/{accountId}/send" \
                  
                    2
                      -H "Content-Type: application/json" \
                  
                    3
                      --data @- <<'BODY'
                  
                    4
                    {
                  
                    5
                      "to": [
                  
                    6
                        "[email protected]"
                  
                    7
                      ],
                  
                    8
                      "subject": "Welcome to Riposte",
                  
                    9
                      "body": "Hi there,\n\nThanks for signing up!",
                  
                    10
                      "isHtml": false
                  
                    11
                    }
                  
                    12
                    BODY
                  
              

Example response 200

              {
  "success": true,
  "result": {
    "success": true,
    "messageId": "msg_01HZY8AW50MP89C11DW00SHM3R",
    "tracking": {
      "id": "trk_cfg_01HZY9A6T4M9S9RJ4K2",
      "token": "token_3f1ac9224a",
      "pixelUrl": "https://links.riposte.co/open/token_3f1ac9224a",
      "snippet": "<img src=\"https://links.riposte.co/open/token_3f1ac9224a\" />",
      "headers": {
        "X-Riposte-Tracking-Token": "token_3f1ac9224a"
      },
      "domain": "links.riposte.co"
    }
  }
}
            

---

GET /accounts/{accountId}/threads

GET /accounts/{accountId}/threads

Parameters

accountId string

In path • Required

Additional parameters

page string

In query • Optional

limit string

In query • Optional

maxResults string

In query • Optional

labelId string

In query • Optional

pageToken string

In query • Optional

searchQuery string

In query • Optional

dateFrom string

In query • Optional

dateTo string

In query • Optional

Returns

Paginated collection of conversation threads.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/threads"
                  
              

Example response 200

              {
  "threads": [
    {
      "id": "thd_01J0B16WSX8M8TE1F4KZ9VQ9ZB",
      "subject": "Customer onboarding call",
      "snippet": "Thanks for confirming the agenda for tomorrow.",
      "participants": [
        "[email protected]",
        "[email protected]"
      ],
      "unreadCount": 1,
      "lastMessageAt": "2024-06-18T21:15:00.000Z",
      "provider": "google"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
            

---

GET /accounts/{accountId}/threads/{threadId}

GET /accounts/{accountId}/threads/{threadId}

Parameters

accountId string

In path • Required

threadId string

In path • Required

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/threads/{threadId}"
                  
              

Example response 200

              {
  "id": "thd_01J0B16WSX8M8TE1F4KZ9VQ9ZB",
  "accountId": "acct_123456789",
  "subject": "Customer onboarding call",
  "participants": [
    "[email protected]",
    "[email protected]"
  ],
  "messageCount": 2,
  "lastMessageDate": "2024-06-18T21:15:00.000Z",
  "snippet": "Looking forward to tomorrow.",
  "labels": [
    "lbl_support"
  ],
  "provider": "google",
  "messages": [
    {
      "accountId": "acct_123456789",
      "from": "[email protected]",
      "to": [
        "[email protected]"
      ],
      "subject": "Agenda for onboarding",
      "body": "<p>Sharing the final agenda.</p>",
      "receivedAt": "2024-06-18T20:30:00.000Z",
      "provider": "google",
      "labels": [
        "lbl_support"
      ],
      "isHtml": true
    }
  ]
}
            

---

GET /accounts/{accountId}/threads/search

GET /accounts/{accountId}/threads/search

Parameters

accountId string

In path • Required

Additional parameters

query string

In query • Optional

subject string

In query • Optional

body string

In query • Optional

from string

In query • Optional

to string

In query • Optional

labelId string

In query • Optional

date_from string

In query • Optional

date_to string

In query • Optional

page string

In query • Optional

limit string

In query • Optional

pageToken string

In query • Optional

Returns

Paginated collection of conversation threads.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/accounts/{accountId}/threads/search"
                  
              

Example response 200

              {
  "threads": [
    {
      "id": "thd_01J0B16WSX8M8TE1F4KZ9VQ9ZB",
      "subject": "Customer onboarding call",
      "snippet": "Thanks for confirming the agenda for tomorrow.",
      "participants": [
        "[email protected]",
        "[email protected]"
      ],
      "unreadCount": 1,
      "lastMessageAt": "2024-06-18T21:15:00.000Z",
      "provider": "google"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
            

---

POST /deliver/

Deliver message to multiple strategies

Internal endpoint for delivering messages to configured delivery strategies and webhooks.

Parameters

This endpoint does not accept parameters.

Request body

Optional • application/json

Request body (application/json)

post-/deliver/-request-body-application/json

object<{ id, provider, accountId, … }>

Field	Type	Description	Values
accountId Optional	string	—	—
id Optional	string	—	—
provider Optional	string	—	—
threadId Optional	string	—	—

Returns

Message delivered successfully

Content type: application/json

Status: 204

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/deliver/" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 204

No example response available.

---

POST /drafts/{draftId}/send

Send email from draft

Send an email from an existing draft

Parameters

draftId string

In path • Required

Unique identifier of the draft stored by Riposte.

                        draft_01HZVBFQ1ZPQF52TJPMM4P5N3S
                      

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/drafts/{draftId}/send"
                  
              

Example response 200

No example response available.

---

POST /send

Send an email or save as draft

Send an email immediately or save as draft. Include tracking options to generate an on-prem token and pixel automatically.

Parameters

This endpoint does not accept parameters.

Request body

Required • application/json

Full-featured payload for sending mail through a specific account with optional tracking.

Request body (application/json)

post-/send-request-body-application/json

object<{ accountId, to, cc, … }>

Full-featured payload for sending mail through a specific account with optional tracking.

Field	Type	Description	Values
accountId Required	string	Identifier of the account that should send the email. min length 1	Example acct_123456789
bcc Optional	array<string>	Optional BCC recipients.	Example [ "[email protected]" ]
body Required	string	Message body formatted as plain text or HTML. min length 1	Example <p>Excited to chat tomorrow at 10am PST.</p>
cc Optional	array<string>	Optional CC recipients.	Example [ "[email protected]" ]
isHtml Optional	boolean	Indicates whether the message body is HTML.	Example true
saveAsDraft Optional	boolean	Persist the message as a draft instead of sending immediately.	Example false
subject Required	string	Email subject line. min length 1	Example Your Riposte demo is scheduled
to Required	array<string>	Primary recipients for the email.	Example [ "[email protected]" ]
tracking Optional	object<{ enabled, domain, tags, … }>	Optional open and click tracking configuration.	—

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/send" \
                  
                    2
                      -H "Content-Type: application/json" \
                  
                    3
                      --data @- <<'BODY'
                  
                    4
                    {
                  
                    5
                      "accountId": "acct_123456789",
                  
                    6
                      "to": [
                  
                    7
                        "[email protected]"
                  
                    8
                      ],
                  
                    9
                      "subject": "Your Riposte demo is scheduled",
                  
                    10
                      "body": "<p>Excited to chat tomorrow at 10am PST.</p>",
                  
                    11
                      "isHtml": true,
                  
                    12
                      "tracking": {
                  
                    13
                        "enabled": true,
                  
                    14
                        "domain": "links.riposte.co",
                  
                    15
                        "tags": [
                  
                    16
                          "product-launch"
                  
                    17
                        ],
                  
                    18
                        "metadata": {
                  
                    19
                          "campaignId": "cmp_launch_2024"
                  
                    20
                        },
                  
                    21
                        "expiresInHours": 168,
                  
                    22
                        "injectPixel": true
                  
                    23
                      }
                  
                    24
                    }
                  
                    25
                    BODY
                  
              

Example response 200

No example response available.