Customer.io
v1.0.0
OpenAPI 3.1.0

Schedule a newsletter

US region

Client Libraries
Shell Curl

Schedule a newsletter

​

Schedule a newsletter to send at a specific time. The newsletter must be in a draft state. If the newsletter has already been sent, you'll get a 400 error. If the newsletter is already scheduled, this endpoint updates the scheduled time.

The recipients for the newsletter are defined when you create/update the newsletter. If you're not sure who will receive the newsletter, you can use the List newsletters endpoint to get a list of newsletters and their recipients.

Path Parameters
  • newsletter_id
    Type: integer
    required

    The identifier of a newsletter.

Body
required
application/json
  • Type: object

    Optional newsletter rate limiting. If you set rate_limit_email_rate or rate_limit_time_period, set both; rate_limit_spread can be set alone.

    • scheduled_at
      Type: integerFormat: unix timestamp
      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.

    • rate_limit_email_rate
      Type: integer
      min:  
      1

      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_spread
      Type: boolean

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

    • rate_limit_time_period
      Type: integerenum

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

      values
      • 60
      • 3600
      • 86400
    • timezone
      Type: string

      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_enabled
      Type: boolean

      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).

Responses
  • application/json
  • application/json
  • 404

    The newsletter does not exist.

  • application/json
  • 429

    Your request is over the 10-per-second limit.

Request Example for post/v1/newsletters/{newsletter_id}/schedule
curl https://api.customer.io/v1/newsletters/1/schedule \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "scheduled_at": 1719849600,
  "timezone": "America/New_York",
  "tz_match_enabled": false,
  "rate_limit_email_rate": 500,
  "rate_limit_time_period": 60,
  "rate_limit_spread": true
}'

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

The newsletter is scheduled for sending.