Schedule Newsletter

Schedules a newsletter for future delivery. Stamps sent=true, date_sent=<sendAt>, and a server-rendered body on the newsletter, then enqueues a Firestore trigger row that fires the actual Sparkpost transmission at sendAt. Does NOT call Sparkpost itself — that happens at fire time. Preconditions checked before scheduling: - Newsletter exists and is owned by the caller's workspace - sendAt is strictly in the future - Newsletter has a non-empty subject - Newsletter has at least one recipient - Newsletter has viewport_data (or a previously-rendered body) — the server renders viewport_data to HTML and persists it as body for the trigger to consume. For immediate transmission, use send_newsletter instead.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Request Body

application/jsonRequired

sendAtRequiredstring

ISO timestamp for delivery. Must be strictly in the future. The newsletter must already have a subject, at least one recipient, and viewport_data (the send pipeline renders it to HTML automatically).

Pattern:

"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"

Format: "date-time"

Path Parameters

idRequiredstring

Newsletter id, discoverable via list_newsletters

POST/v1/newsletters/{id}/schedule

curl -X POST "https://api.3common.com/v1/newsletters/string/schedule" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sendAt": "2019-08-24T14:15:22Z"
  }'

Default Response

Response

{
  "data": {
    "id": "string",
    "hostId": "string",
    "subject": "string",
    "body": "string",
    "sent": true,
    "recipient_emails": [
      "string"
    ],
    "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
  }
}

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_emails: string[];
    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;
    /**
     * Set on summary projections from the paginated list endpoint
     */
    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;
  };
}