Create and send a one-time send

Server

US region

Client Libraries

Shell Curl

Create and send a one-time send

Create a one-time send (referred to as a "newsletter" in our APIs) and optionally schedule it or send it immediately.

Set the audience with either recipients (a filter over segments and profile attributes) or recipient_file_url (a CSV of recipients). One of the two is required, and a request carrying both is rejected.

To send it 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, it's created as a draft.

A recipient_file_url audience resolves in the background, so you can't send or schedule in the same request. Poll Get a one-time send until recipient_file_status is done, then call send or schedule.

There's no endpoint that updates a one-time send, so name, the audience, and deduped are fixed once you create it. To change them on a draft, delete it and create a new one. You can still edit content through the variant endpoints until it sends.

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: object · Email
type
Discriminator
enum
const:
email
required

The channel type for the one-time send.

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 one-time send.

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.

deduped
Type: boolean

When true, Customer.io sends only one message per email address or phone number, even when several profiles share it. Supported on email, twilio, and sms one-time sends. Leave it out to use the default for your workspace's identifier configuration. No endpoint changes this later, so set it here if you don't want the default.

expires_after
Type: integer
min:
0
max:
2592000

A send window in seconds, or 0 for no expiry. Customer.io stops delivering the one-time send once the window closes, so a delayed message doesn't arrive when it's no longer useful. Set it here only alongside send_now or scheduled_at, because the window runs from the send. On a plain draft, set it on the send or schedule call instead.

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: integer enum

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

values
60
3600
86400
recipient_file_url
Type: string Format: uri

A URL pointing to a CSV of recipients, used instead of the recipients filter. Customer.io resolves the file in the background, so this request can't also send or schedule. Poll Get a one-time send until recipient_file_status is done, then call send or schedule.

recipients
Type: object

Filter conditions that define the one-time send's recipients. In recipients, you can 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.

scheduled_at
Type: integer Format: unix timestamp

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

send_now
Type: boolean

If true, the one-time send is sent immediately after creation. You cannot set both send_now and scheduled_at.

subscription_topic_id
Type: integer

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

tag_ids
Type: array integer[]

The IDs of the tags you want to apply to the one-time send. Each tag must already exist.

Responses

application/json
application/json
application/json
application/json

post/v1/newsletters

{
  "type": "email",
  "body": "<html><body><h1>Product Updates</h1><p>Here's what we shipped this week...</p></body></html>",
  "name": "Weekly Product Update",
  "subject": "What's new this week, {{ customer.first_name }}",
  "from": "Product Team <updates@example.com>",
  "preheader_text": "Check out our latest features and improvements",
  "rate_limit_email_rate": 500,
  "rate_limit_spread": true,
  "rate_limit_time_period": 60,
  "recipients": {
    "and": [
      {
        "or": [
          {
            "segment": {
              "id": 42
            }
          },
          {
            "segment": {
              "id": 99
            }
          }
        ]
      },
      {
        "attribute": {
          "field": "plan",
          "operator": "eq",
          "value": "enterprise"
        }
      }
    ]
  },
  "send_now": true,
  "subscription_topic_id": 5
}

Show Schema

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

Returns the newly created one-time send.

Create and send a one-time send

Authentication

Create and send a one-time send