Create and send a newsletter

Server

US region

Client Libraries

Shell Curl

Create and send a newsletter

Create a newsletter and optionally schedule it or send it immediately.

To send the newsletter immediately, set send_now to true. To schedule for later, set scheduled_at to a Unix timestamp in the future. If you don't set either, the newsletter is created as a draft.

If you enabled a subscription center in your workspace, subscription_topic_id is required. Use the subscription center endpoint to find IDs.

Use standard HTML/CSS for the body of an email; this endpoint can't pull in global style variables or render our Design Studio's component syntax. You can create Design Studio emails through other endpoints. All requests must be less than 1 MB.

Body

required

application/json

When you create an email, include subject and body. Set either from or from_id, but not both. If you set neither, Customer.io uses your oldest verified sending address.

type
Discriminator
enum
const:
email
required

The channel type for the newsletter.

values
email
body
Type: string
required

The HTML body content of the email. Use standard HTML/CSS, not syntax unique to Design Studio.

name
Type: string
max length:
190
required

The name of the newsletter.

recipients
Type: object
required

Filter conditions that define the newsletter's recipients. Combine segment and attribute conditions with and, or, and not operators.

This endpoint enforces a strict shape:

The outermost object must be a single and array.

Every operator or condition object takes exactly one key: and, or, not, segment, or attribute. An object with two keys—like not alongside and—is rejected with an "Invalid filter spec" error.

Segment conditions must be wrapped in an or array, even for a single segment—and or arrays can contain only segment conditions.

To exclude segments, not must contain an or of segment conditions and sit as its own item inside the and array.

Attribute conditions sit directly in the and array, unwrapped. To negate an attribute condition, set inverse: true on the attribute itself—not can't contain attribute conditions.

The email example on this operation shows or-wrapped segments combined with a negated attribute; for the common "include segment A, exclude segment B" pattern, see the include one segment, exclude another request example. See Format API-triggered broadcasts for general operator behavior.

subject
Type: string
required

The subject line of the email.

body_plain
Type: string

The plaintext body of the email. If provided, this overwrites the auto-generated plaintext.

from
Type: string

The address to send the email from, in the format Name <email@domain.com>. You can set from or from_id, but not both. Use one of the address values from List sender identities.

from_id
Type: integer

The identifier of the from address, commonly known as the "sender". Use List sender identities to find valid IDs.

layout_id
Type: integer

The ID of the layout you want to use for the email. If you don't set one, the email uses your workspace's default layout. Find a layout's ID in its URL.

preheader_text
Type: string

Also known as "preview text", this is the small block of text shown in an email inbox next to or underneath the subject line.

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

A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both send_now and scheduled_at.

send_now
Type: boolean

If true, the newsletter is sent immediately after creation. You cannot set both send_now and scheduled_at.

subscription_topic_id
Type: integer

The newsletter audience's subscription topic ID. Required when subscription center is enabled; otherwise sends to globally subscribed profiles.

Responses

application/json
application/json
application/json
429

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

post/v1/newsletters

curl https://api.customer.io/v1/newsletters \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Weekly Product Update",
  "type": "email",
  "recipients": {
    "and": [
      {
        "or": [
          {
            "segment": {
              "id": 42
            }
          },
          {
            "segment": {
              "id": 99
            }
          }
        ]
      },
      {
        "attribute": {
          "field": "plan",
          "operator": "eq",
          "value": "enterprise"
        }
      }
    ]
  },
  "send_now": true,
  "subject": "What'\''s new this week, {{ customer.first_name }}",
  "preheader_text": "Check out our latest features and improvements",
  "body": "<html><body><h1>Product Updates</h1><p>Here'\''s what we shipped this week...</p></body></html>",
  "from": "Product Team <updates@example.com>",
  "subscription_topic_id": 5,
  "rate_limit_email_rate": 500,
  "rate_limit_time_period": 60,
  "rate_limit_spread": true
}'

Show Schema

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

Returns the newly created newsletter.

Create and send a newsletter

Authentication

Create and send a newsletter