CUcustomer
Send Messages

Schedule a one-time send

Changed on

Schedule a one-time send (referred to as a "newsletter" in our APIs) to send at a specific time. It must be in a draft state. If it has already been sent, you'll get a 400 error. If it's already scheduled, this endpoint updates the scheduled time.

The response returns the one-time send, so you can read back the schedule you set: send_state and scheduled_at are always included, and timezone and tz_match_enabled are included when they apply.

To retrieve the schedule parameters after scheduling with Get a one-time send. After you start a send with timezone-match, scheduled_at reports the next timezone batch or the remainder of an A/B test instead of the time you requested.

The recipients are fixed when you create the one-time send. If you're not sure who will receive it, you can use the List one-time sends endpoint to get a list of one-time sends and their recipients.

post/v1/newsletters/{newsletter_id}/schedule

Request

  • Base URL
    https://api.customer.io
  • URL
    https://api.customer.io/v1/newsletters/{newsletter_id}/schedule
  • Auth
    HTTP bearer

Request body

scheduled_atinteger required

Unix timestamp for the send. Use 0 to deschedule. When greater than 0, the time must be in the future and you must send timezone so the UI displays the time correctly.

timezonestring

IANA timezone name (for example, America/New_York). Required when scheduled_at is greater than 0. Not required when descheduling (scheduled_at is 0).

tz_match_enabledboolean

When true, sends at the same local time in each recipient's timezone. If it's set to true and rate_limit_time_period is provided, then the period can't be greater than 3600 (1 hour).

expires_afterinteger

A send window in seconds measured from the scheduled time, or 0 for no expiry. Customer.io stops delivering the one-time send once the window closes. You can't combine it with tz_match_enabled, with send time optimization, or with descheduling (scheduled_at of 0), and on an A/B test it must outlast the test duration.

rate_limit_email_rateinteger

Maximum number of messages per time period. NOTE: Though this states email_rate, you can use this for other message channels. Only fixed rate limits are supported, not daily ramp limits.

rate_limit_time_period60 | 3600 | 86400

Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day).

rate_limit_spreadboolean

When true, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period.

Example request

{
  "rate_limit_email_rate": 500,
  "rate_limit_time_period": 60,
  "rate_limit_spread": true
}

Response

The one-time send is scheduled for sending.

Example response

{
  "newsletter": {
    "id": 128275,
    "deduplicate_id": "128275:1481653929",
    "type": "email",
    "content_ids": [
      45
    ],
    "name": "Weekly Product Update",
    "sent_at": 1481653929,
    "send_state": "sent",
    "scheduled_at": null,
    "created": 1481653919,
    "updated": 1481653929,
    "recipient_segment_ids": [
      42,
      99
    ],
    "tags": [
      "Product Updates"
    ],
    "subscription_topic_id": 5
  }
}

Changes

  • f3a28f896929Revision changes
    • breaking

      the response property / became nullable for the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 7aca33a41082Revision changes
    • info

      added the new optional request property /

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status