Skip to content
EmailShepherdEmailShepherdDocumentation

List Emails

GET
/api/v1/workspaces/{workspace_id}/emails
curl --request GET \
  --url 'https://example.com/%7B%7Bapp_url%7D/api/v1/workspaces/1/emails?per=10&page=1&email_folder_id=root&status=draft&sort=created_at_asc' \
  --header 'Authorization: Bearer <token>'

Retrieves the Emails the user has access to.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
workspace_id
required
integer

Workspace ID

Query Parameters

Section titled “Query Parameters”
per
integer
default: 10

Number of records per page

page
integer
default: 1

Page number

project_id
integer

Filter emails by project ID

email_folder_id
string
Example
root

Filter emails by folder. Pass a folder ID to list the emails in that folder, or the string ‘root’ to list emails not in any folder. When omitted, emails from all folders are returned.

status
string
Allowed values: draft in_review changes_requested approved published

Filter emails by status

search
string

Filter emails by search term, matching against the email’s name or content.

sort
string
Allowed values: created_at_asc created_at_desc updated_at_asc updated_at_desc name_asc name_desc

Sorting

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful

Media typeapplication/json
object
results
required
Array<object>
object
id
required
integer
status
required
string
Allowed values: draft in_review changes_requested approved published
name
required
string
project_id
required
integer
email_folder_id
required

The ID of the folder this email is in, or null if it is at the root of the project.

integer | null
created_at
required
string format: date-time
organization_id
required
integer
email_design_system_id
required
integer
default_locale
required

A BCP 47 language tag identifying the language and region of a piece of content. Must carry both a language and a region subtag, and must be in canonical case (lowercase language, titlecase script, uppercase region) — en-GB, not en-gb or en_GB. The region may be a UN M.49 code, so en-001 (world) is valid.

string
locales
required
Array<string>
updated_at
required
string format: date-time
last_updated_by
required
One of:
One of:
object
type
required
string
Allowed values: User
id
required
integer
first_name
required
string
last_name
required
string
profile_image_url
required
string | null
ai_edit_in_progress
required
boolean
translation_in_progress
required
boolean
brand_profile_id
required
integer | null
link_tracking_profile_id
required
integer | null
published_at
required
string | null format: date-time
screenshot_url
required
string
pagination
required
object
per
required
integer
page
required
integer
total
required
integer
Example
{
  "results": [
    {
      "id": 12345,
      "status": "draft",
      "name": "My Email",
      "project_id": 12345,
      "email_folder_id": 12345,
      "created_at": "2023-08-23T10:30:00.000Z",
      "organization_id": 12345,
      "email_design_system_id": 12345,
      "default_locale": "en-GB",
      "locales": [
        "en-GB"
      ],
      "updated_at": "2023-08-23T10:30:00.000Z",
      "last_updated_by": {
        "type": "User",
        "id": 12345,
        "first_name": "John",
        "last_name": "Smith",
        "profile_image_url": "https://example.com/profile.jpg"
      },
      "ai_edit_in_progress": false,
      "translation_in_progress": false,
      "brand_profile_id": 12345,
      "link_tracking_profile_id": 12345,
      "published_at": "2023-08-23T10:30:00.000Z",
      "screenshot_url": "https://www.example.com/screenshot.png"
    }
  ],
  "pagination": {
    "per": 10,
    "page": 1,
    "total": 100
  }
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
message
required
string
code
string
Example
{
  "message": "Record not found",
  "code": "share_link_expired"
}

404

Section titled “404”

Not Found

Media typeapplication/json
object
message
required
string
code
string
Example
{
  "message": "Record not found",
  "code": "share_link_expired"
}