CUcustomer
Newsletters

Create and send a one-time send

Changed on

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.

post/v1/newsletters

Request

  • Base URL
    https://api.customer.io
  • URL
    https://api.customer.io/v1/newsletters
  • Auth
    HTTP bearer

Request body

OR
OR
OR
OR
OR

Example request

{
  "name": "Weekly Product Update",
  "type": "email",
  "recipients": {
    "and": [
      {
        "or": [
          {
            "segment": {
              "id": 42
            }
          },
          {
            "segment": {
              "id": 99
            }
          }
        ]
      },
      {
        "attribute": {
          "field": "plan",
          "operator": "eq",
          "value": "trial",
          "inverse": 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
}

Response

Returns the newly created one-time send.

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 new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      the request property ///// became optional

    • info

      the request property ///// became optional

    • info

      the request property ///// became optional

    • info

      the request property ///// became optional

    • info

      the request property ///// became optional

    • info

      the request property ///// became optional

    • 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