List Newsletters

Lists the workspace's newsletters, optionally filtered by view (draft / past). Paginated; returns recipient-stripped summaries so list payloads stay small. Sorted by updatedAt descending.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Query Parameters

viewstring

Filter by view; omit to include drafts + sent + scheduled.

Value in: "past" | "sent" | "scheduled" | "draft"

pageNumberinteger

Page number (0-based, default 0)

Default: 0Minimum: 0Maximum: 9007199254740991

pageSizeinteger

Items per page (default 20, max 100)

Default: 20Minimum: 1Maximum: 100

sortFieldstring

Field to sort results by. Omit for default (updatedAt descending).

Value in:

"_id" | "subject" | "sent" | "date_sent" | "recipient_count" | "automatic" | "sync_event_recipients" | "data_version" | "createdAt" | "updatedAt"

sortDirectionstring

Sort direction. Defaults to desc when sortField is provided.

Value in: "asc" | "desc"

filtersstring

JSON-encoded FilterGroup[] for custom filtering. Conditions referencing fields outside the persisted newsletter schema are silently ignored. ANDed with the 'view' filter when both are supplied.

fieldsstring

Comma-separated list of fields to return. Valid: id, hostId, subject, sent, date_sent, recipient_count, reply_to_email, display_name, automatic, data_version, sync_event_recipients, createdAt, updatedAt, sparkpost_metrics, attachments. Omit for all fields.

GET/v1/newsletters/

curl -X GET "https://api.3common.com/v1/newsletters/?view=past&sortField=_id&sortDirection=asc&filters=string&fields=string" \
  -H "Authorization: Bearer <token>"

Default Response

Response

{
  "data": [
    {
      "id": "string",
      "hostId": "string",
      "subject": "string",
      "body": "string",
      "sent": true,
      "recipient_phonenumbers": [
        "string"
      ],
      "event_refs": [
        "string"
      ],
      "timeslot_refs": [
        "string"
      ],
      "date_sent": "2019-08-24T14:15:22Z",
      "footer_image": "string",
      "reply_to_email": "string",
      "automatic": true,
      "display_name": "string",
      "content_blocks": [
        null
      ],
      "viewport_data": null,
      "data_version": 0,
      "sync_event_recipients": true,
      "recipient_count": -9007199254740991,
      "attachments": [
        {
          "name": "string",
          "size": 9007199254740991,
          "url": "string",
          "type": "string",
          "uploading": true,
          "uploadError": "string",
          "storagePath": "string"
        }
      ],
      "sparkpost_metrics": {
        "count_sent": -9007199254740991,
        "count_delivered": -9007199254740991,
        "count_opens": -9007199254740991,
        "count_clicks": -9007199254740991,
        "count_bounce": -9007199254740991,
        "count_unsubscribe": -9007199254740991,
        "bounce_rate": "string",
        "open_rate": "string",
        "click_rate": "string",
        "revenue_generated": -9007199254740991,
        "fetched_at": 0
      },
      "createdAt": 0,
      "updatedAt": 0
    }
  ],
  "hasMore": true,
  "pageNumber": -9007199254740991,
  "pageSize": -9007199254740991
}

TypeScript

export interface Response {
  data: {
    id?: string;
    hostId?: string;
    subject?: string;
    /**
     * Rendered HTML — empty for drafts
     */
    body?: string;
    /**
     * False for drafts, true for sent / scheduled
     */
    sent?: boolean;
    recipient_phonenumbers?: string[];
    event_refs?: string[];
    timeslot_refs?: string[];
    date_sent?: string;
    footer_image?: string;
    reply_to_email?: string;
    automatic?: boolean;
    display_name?: string;
    /**
     * Deprecated legacy content shape; new newsletters use viewport_data
     */
    content_blocks?: unknown[];
    /**
     * Site-builder viewport_data — structured email content rendered to HTML by the send pipeline
     */
    viewport_data?: {
      [k: string]: unknown;
    };
    /**
     * Content storage discriminator.
     * - 0 (CONTENT_BLOCKS, deprecated): legacy content_blocks array
     * - 1 (VIEWPORT_DATA): site-builder viewport_data shape
     */
    data_version?: 0 | 1;
    sync_event_recipients?: boolean;
    recipient_count?: number;
    attachments?: {
      /**
       * Original filename
       */
      name: string;
      /**
       * File size in bytes
       */
      size: number;
      /**
       * Publicly fetchable URL (Firebase Storage download URL in practice)
       */
      url: string;
      /**
       * MIME type
       */
      type: string;
      /**
       * True while the attachment upload is in progress; false or omit once it finishes
       */
      uploading?: boolean;
      /**
       * Surfaced when an attachment upload failed
       */
      uploadError?: string;
      /**
       * Firebase Storage path for deletion
       */
      storagePath?: string;
    }[];
    sparkpost_metrics?: {
      count_sent: number;
      count_delivered: number;
      count_opens: number;
      count_clicks: number;
      count_bounce: number;
      count_unsubscribe: number;
      /**
       * Pre-formatted percentage, e.g. "2.3%"
       */
      bounce_rate: string;
      open_rate: string;
      click_rate: string;
      /**
       * Revenue attributed via referral tracking, minor units
       */
      revenue_generated?: number;
      /**
       * Epoch ms when these metrics were last fetched from Sparkpost
       */
      fetched_at?: number;
    };
    /**
     * Creation timestamp, ms since epoch
     */
    createdAt?: number;
    /**
     * Last-updated timestamp, ms since epoch
     */
    updatedAt?: number;
  }[];
  hasMore: boolean;
  pageNumber: number;
  pageSize: number;
}