Send Newsletter

Sends a newsletter through Sparkpost immediately. Stamps date_sent + sent=true on the persisted document. Seamless flow: call with just `id` once the draft has subject, recipients, viewport_data, and reply_to_email set. The server pulls those fields from the persisted doc and renders viewport_data → HTML server-side if no body is already rendered. Only pass subject/senderName/replyToEmail/recipients/html/attachments when you explicitly need to override the persisted values for this one send. The Sparkpost API must be configured server-side; calls return 503 when SPARKPOST_API_KEY is unset.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Request Body

application/jsonRequired

htmlstring

Pre-rendered HTML body. Usually omitted — the server renders viewport_data automatically if no body is persisted. Supply only when you need to override the persisted body for this one send.

subjectstring

Override the persisted subject for this send. Newlines are stripped server-side.

senderNamestring

Override the persisted display_name on the From line.

replyToEmailstring

Override the persisted reply_to_email.

recipientsarray<string>

Override the persisted recipient list. Typo-domain addresses are stripped server-side.

attachmentsarray<object>

Override the persisted attachments. URLs are downloaded and base64-encoded before transmission to Sparkpost.

Path Parameters

idRequiredstring

Newsletter id, discoverable via list_newsletters

POST/v1/newsletters/{id}/send

curl -X POST "https://api.3common.com/v1/newsletters/string/send" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "string",
    "subject": "string",
    "senderName": "string",
    "replyToEmail": "string",
    "recipients": [
      "string"
    ],
    "attachments": [
      {
        "name": "string",
        "size": 9007199254740991,
        "url": "string",
        "type": "string",
        "uploading": true,
        "uploadError": "string",
        "storagePath": "string"
      }
    ]
  }'

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;
  };
}