POST emails/test

Overview

POST /v2/emails/test triggers a specific email template personalized for a specific user and sent to one or more email addresses. These recipients do not have to be subscribers. Optionally, the personalization values for the subscriber can be over-ridden using the profile object. Messages sent using this method have their subjectline prepended with PREVIEW. Key performance metrics associated with these messages are not available through any means.

 

Resource URI

 https://api.yesmail.com/v2/emails/test

Call Description

In addition to the standard response headers, this API call will also provide a header Content-Location: https://api.yesmail.com/v2/tickets/{id}, which provides the location of the ticket resource where status information is updated. See Tickets API documenation for more details.

URI Parameters

Parameter

Required

Description

responseUri 

 Optional

A customer-specified URI where Yesmail’s service can post the final status of the request.  See Tickets API documentation for more details.

responseRef 

 Optional

A customer-specified value that the customer may wish to use to track the ticket internally.  See Tickets API documentation for more details.

Parameters

Parameter

Required

Description

content

Mandatory

A collection consisting of a single element.

templateId (mandatory). The templateID of the message template to be sent

recipients

Mandatory

An array consisting of the recipients of the email.  This request supports up to 300 recipients.  Each recipient is specified as a collection containing the following elements:

  • id (optional). Customer-defined unique ID.  Required if updateProfile=true.
  • email (mandaory). The subscriber's email address. One of either id or email must be specified, and if the recipient is not in the subscribers database, both id and email are required.
  • profile (optional). A collection consisting of subscriber attributes.  In current implementation, must consist of a single “userAttrs” array.  

HTTP Return Codes

Code

Description

202 Accepted

The request has been entered into the queue.

400 Bad Request

The request could not be understood by the server due to malformed syntax.  For example, incorrect syntax of parameters, invalid parameter values, subscriber attribute does not exist, missing email address for new subscriber, or subscriber email address is mixed case and fails superficial validation.

401 Unauthorized

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

404 Not Found

A 404 Not Found response is returned if the template ID or render-subscriber ID is not found. It is not necessary for the subscriber to have an active subscription, it must just exist in the system.

Request Payload: 
{
  "content": {
    "templateId": "678678"
  },
  "renderSubscriber": {
    "id": "john.doe@somedomain.com",
    "profile": {
      "userAttrs": [
        { "firstname": "John" },
        { "lastname": "Doe" }
      ]
    }
  },
  "recipients": [
    { "email": "recipient1@domain.com" },
    { "email": "recipient2@otherdomain.com" }
  ]
}
Response Payload: 
{
  "id": "ticket id",
  "state": "accepted | failed",
  "message": "Current status description for humans",
  "lastUpdate": "UTC based timestamp when ticket was created",
  "events": [
   {
     "state": "accepted | processing | completed | failed",
     "message": "Status description",
     "time": "UTC based timestamp when ticket was created"
   }
 ],
 "request" : {
   "id": "<UUID tracking ID>",
   "user": "API-User header value from the request",
   "time": "UTC based timestamp when the request was received",
   "uri": "Request URI used by the caller",
  },
  "response": {
    "uri": "Optional URI to POST to when status reached completed or failed",
    "ref": "Optional reference value provided by the caller"
  }
}
{
  "id": "9876543210",
  "lastUpdate": "2014-02-11T16:08:32Z",
  "counts": {
    "completed": 1,
    "failed": 1,
    "ignored": 1,
    "total": 2,
    "requested": 3
  }
  "completed ": [
    {
      "index": 0,
      "time": "2014-02-11T16:08:22Z",
      "location": "https://api.yesmail.com/v2/subscribers/name%40domain.com"
    }
  ],
  "failed": [
    {
      "index": 1,
      "time": "2014-02-11T16:08:32Z",
      "error": {
        "status": 409,
        "message": "Conflict while inserting a subscriber",
        "moreInfo": "https://developer.yesmail.com/errors/subscriber-insert-conflict"
      }
    }
  ],
  "ignored": [
    { "index": 2 }
  ]
}