Messages

18 endpoints

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

GET /{id}/threads

GET /{id}/threads

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

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

Example response 200

No example response available.

---

GET /{id}/threads/{threadId}

GET /{id}/threads/{threadId}

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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/{id}/threads/{threadId}"
                  
              

Example response 200

No example response available.

---

GET /{id}/threads/search

GET /{id}/threads/search

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

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

Example response 200

No example response available.

---

GET /accounts/{id}/messages

Fetch messages from account

Get a paginated list of messages from a specific email account

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

                        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
                          

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/{id}/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/{id}/messages/{messageId}

Delete a message

Permanently delete a message from the provider inbox.

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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/{id}/messages/{messageId}"
                  
              

Example response 204

No example response available.

---

GET /accounts/{id}/messages/{messageId}

Get a single message with labels

Retrieve a specific message with all its labels and metadata

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

messageId 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/{id}/messages/{messageId}"
                  
              

Example response 200

No example response available.

---

PUT /accounts/{id}/messages/{messageId}

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

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

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

messageId string

In path • Required

Request body

Optional • application/json

Request body (application/json)

put-/accounts/{id}/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

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

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

Example response 200

No example response available.

---

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

List attachments for a message

Get a list of all attachments for a specific message

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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/{id}/messages/{messageId}/attachments"
                  
              

Example response 200

No example response available.

---

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

Upload attachment to message

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

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

messageId string

In path • Required

Request body

Required • application/json

Request body (application/json)

post-/accounts/{id}/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

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

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

Example response 200

No example response available.

---

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

Download a message attachment

Download a specific attachment from a message

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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/{id}/messages/{messageId}/attachments/{attachmentId}"
                  
              

Example response 200

No example response available.

---

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

Forward a message

Forward an existing message to other recipients

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

messageId string

In path • Required

Request body

Required • application/json

Request body (application/json)

post-/accounts/{id}/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/{id}/messages/{messageId}/forward" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

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

---

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

Get raw MIME message

Retrieve the full RFC822 MIME payload for a message.

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

messageId 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/{id}/messages/{messageId}/raw"
                  
              

Example response 200

No example response available.

---

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

Reply to a message

Reply to an existing message

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

messageId string

In path • Required

Request body

Required • application/json

Request body (application/json)

post-/accounts/{id}/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

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/{id}/messages/{messageId}/reply" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

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

---

GET /accounts/{id}/messages/search

Search messages

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

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

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 (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

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

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

Example response 200

No example response available.

---

POST /accounts/{id}/send

Send message through account

Send an email message through the specified account

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

                        acct_123456789
                      

Request body

Required • application/json

Simplified payload for sending a message using default account settings.

Request body (application/json)

post-/accounts/{id}/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

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/accounts/{id}/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

No example response available.

---

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/{id}/send

Send email from draft

Send an email from an existing draft

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

                        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/{id}/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.