POST masters

Overview

A master is an amalgamation of components that make up a message, which can be personalized and targeted to a specific group of subscribers. It includes the delivery information, the schedule for delivery, the targeting, the message envelope, content, and attachments. The POST /v2/masters call accepts the minimum values required to create a master, which are name, subscription, subject, from address and encoding.

Resource URI

 https://api.yesmail.com/v2/masters

Call Description

The POST /v2/masters call creates a master and returns the id, default delivery values and template (envelope).

Delivery Parameters

Parameter Required Description
maxRecipients

default=no limit

Maximum number of recipients to send from this master. Once it mails to this number, even if there are more eligible records, it will not mail anymore, unless you increase this number again. This is true for all recurrences of the message.

multiDeliveries

default=false

Allows for multiple deliveries of the master to the same recipient. Disables seed lists if set to true.

obeyCompanyLimits

default=true

Controls whether company delivery limits of 3 messages per day per customer are obeyed for this master. Usually set to true for marketing messages and false for transactional messages.

obeyUserLimits

default=true

Controls whether the email counts against the per-user-limit. Transactional emails are typically set to false.

priority default=1 Integer value between 1 (default) and 100. Indicates the priority compared to other masters scheduled at the same time.
rate Optional sets the maximum number of messages to deliver per hour.
type default=auto
  • auto - Will send the HTML version to recipients who have requested to receive HTML, and plain text to those who have requested to received Plain Text. If no preference is stated, then a multipart-MIME with both versions is sent. Both HTML and text body content must be defined.
  • normal - Will send the HTML version to recipients who have requested to receive HTML, and plain text to those who have requested to received Plain Text. If no preference is stated, then the plain text is sent. If there is no HTML version, then all recipients will receive the plain text version regardless of the user preference. Only text body content is required.
  • both - Will send a multipart-MIME with both versions regardless of the user preference. Both HTML and text body content must be defined.

HTTP Return Codes

Code

Description

201 Created

The request has succeeded and the master created.

400 Bad Request Request parameters were invalid, e.g. Name already exists, wrong encoding format, invalid subscription value, subject longer than 72 characters

401 Unauthorized

The request requires user authentication.  Invalid Api-User and/or Api-Key header value.

Request

Create a simple message.

{
  "name": "May Newsletter",
  "subscription": "banjo lovers",
  "template": {
    "encoding": "UTF-8",
    "from": [
      {
        "email": "marketing@banjo.com",
        "name": "Jimmi Mac"
      }
    ],
    "subject": [ "The new strings are here!" ]
    }
}

Response

Response includes all default delivery values.

{
    "id": "63189370",
    "lastUpdate": "2015-05-22T23:35:01.554Z",
    "name": "May Newsletter",
    "status": "disabled",
    "subscription": "banjo lovers",
    "delivery": {
        "type": "auto",
        "lastSend": "4000-01-01T00:00:00.000Z",
        "multiDeliveries": false,
        "obeyCompanyLimits": true,
        "countsTowardCompanyLimit": true,
        "priority": 1
    },
    "template": {
        "encoding": "UTF-8",
        "from": [
            {
                "email": "enterprisejt3@magellanjt3.p0.com",
                "name": "Jimmi Mac"
            }
        ],
        "subject": [
            "The new strings are here!"
        ]
    }
}