POST emails/send

Overview

POST /v2/emails/send triggers a specific email template to specified recipients whether they are subscribed or not. Optionally, this call can add or remove subscriptions, update the users profile or set list of recipients as referred.

This call may also be used to modify the subscriber's subscriptions, by using an optional "subscriptions" collection in the request payload.  Within this collection, the following arrays are allowed:

  • "add": Provides a list of subscriptions to be subscribed to
  • "remove": Provides a list of subscriptions to be unsubscribed from ("Remove": ["*"] can be used to unsubscribe from all subscriptions)
  • "setReferred": Sets the recipients global status as referred. Only for new or unscribered recipients.
  • "isMemberOf": Checks the subscription value of the recipient. If they are not subscribed to that division and transactional is false, then they are not mailed.

Order of operations:  If both "add" and "remove" are present, then the "remove" operation is performed before the "add" operation.

Messages sent through this resource do not count towards a subscriber's daily limits.

Resource URI

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

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
transactional

Optional

default=false

A flag that specifies whether the email is transactional (to be sent regardless of subscription status) or not.

transactional = false. Do not send email if recipient is globally unsubscribed, “dead”, or not subscribed to at least one of the subscriptions specified in the “subscriptions” isMemberOf payload element.

transactional = true. Send email regardless of subscription status.

updateProfile

Optional

default=false

A flag that specifies whether any profile information should be updated in the database.

true = Perform database update only for all elements in request payload profile, equivalent to POST subscribers/{id}/update.

false =Do not do so.

content

Mandatory

A collection consisting of a single element.

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

forwarder Optional

Forward to a Friend (FtaF) facilitates 3rd party message delivery applications. Using content personalization, emails can include a note, name personalization, and  reply-to address of the forwarder. setReferred is required and must be set to newOrNotSubscribed.

  • id (optional). Customer-defined unique ID.  Required if updateProfile=true.
  • note (optional). A personalized message for the recipients.
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. Email must be in lower case. Mixed case emails will be rejected with a 400 Bad Request response.
  • profile (optional). A collection consisting of subscriber attributes.  In current implementation, must consist of a single “userAttrs” array.  If updateProfile = false, these attributes will be used only for personalization of the email being sent.  If updateProfile = true, the database will be updated with any attributes provided (as well as being used for personalization as appropriate).

    • subscriptions (optional). A collection consisting of up to two arrays:
      • add (optional). An array of subscriptions to which the subscriber is to be subscribed, in conjunction with sending the email.
      • remove (optional). An array of subscriptions to which the subscriber is to be unsubscribed, in conjunction with sending the email.
        • remove:[“*”] is permitted; this unsubscribes from all subscriptions.
      • setReferred (optional). Sets the recipient as referred, which is a not subscribed state. Required when using forwarder. newOnly sets the subscriber status to "referred" only for new subscribers, otherwise the element is ignored. newOrNotSubscribed sets the subscriber status to "referred" if the subscriber is new, or not subscribed to any division.
        • If both add and remove are specified, the remove operation takes place before the add operation.
        • If add and setReferred are specified, setReferred is ignored.
        • If remove and setReferred are specified and setReferred is set to newOnly then setReferred is ignored, otherwise the subscribers status is set to referred.

      • isMemberOf(optional). An array of subscriptions which will be checked for subscription status if transactional = false. The subscriber must be subscribed to at least one of the subscriptions in this array.  This check is performed after any add or remove processing.

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.

409 Conflict

This occurs under two conditions.

1. The If-Match condition is used (or assumed), and the specified ETag does not match the current ETag for the resource. 

2. User already exists and had unsubscribed from the division

Request

This subscribe and send request will add the new subscriber to two subscriptions and store his profile values.

{
    "content": {
        "templateId": "1465362"
    },
	"updateProfile": true,
    "recipients": [
        {
            "email": "jerry.garcia@yesmail.com",
            "id": "jerry.garcia@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "Garcia"
                    },
			{
			"firstName": "Jerry"
			},
			{
			"Birth Date": "1942-08-01"
			}
 
                ]
            },
            "subscriptions": {
                "add": [
                    "Banjo Lovers",
		    "9 finger club"
                ]
            }
        }
    ]
}

Response

The initial response includes the Ticket response. The content location in the header or the id value in the response body can be used to look up the final request status.

{
    "events": [
        {
            "message": "Send email request queued successfully.",
            "state": "accepted",
            "time": "2014-08-22T23:09:33.340Z"
        }
    ],
    "id": "53f7cdad3f3e5a25780c5be8",
    "lastUpdate": "2014-08-22T23:09:33.340Z",
    "message": "Send email request queued successfully.",
    "request": {
        "id": "ad60d17a-776c-41a9-9dd5-f023cf8ae93c",
        "time": "2014-08-22T23:09:33.000Z",
        "uri": "https://api.yesmail.com/v2/emails/send",
        "user": "adaptivemarketing"
    },
    "response": null,
    "state": "accepted"
}

The retry state is where the requests are put into a retrying queue.

{
"state": "completed",
"message": "Send email request completed.",
"request":
{ "id": "8d71c129-1384-4ec8-bc82-8e83996c02b8", "user": "jefftronics3", "time": "2017-05-22T18:36:57.000Z", "uri": "https://api.qa.yesmail.com/v2/emails/send?responseRef=testingForTheMan" }
,
"response": {
"uri": null,
"ref": "testingForTheMan",
"data":
{ "messageId": "574304811120", "sentTime": "2017-05-22T18:47:02.974Z" }
},
"events": [
{ "state": "accepted", "message": "Send email request queued successfully.", "time": "2017-05-22T18:36:57.998Z" }
,
{ "state": "retrying", "message": "Send email request is being retried because com.yesmail.subscribers.client.exception.SubscriberClientException: com.yesmail.subscribers.client.exception.SubscriberClientException: Connection reset", "time": "2017-05-22T18:37:53.096Z" }
,
{ "state": "retrying", "message": "Send email request is being retried because com.yesmail.subscribers.client.exception.SubscriberClientException: com.yesmail.subscribers.client.exception.SubscriberClientException: Connection reset", "time": "2017-05-22T18:42:26.019Z" }
,
{ "state": "retrying", "message": "Send email request is being retried because com.yesmail.subscribers.client.exception.SubscriberClientException: com.yesmail.subscribers.client.exception.SubscriberClientException: Connection reset", "time": "2017-05-22T18:43:35.459Z" }
,
{ "state": "completed", "message": "Send email request completed.", "time": "2017-05-22T18:47:03.693Z" }
],
"lastUpdate": "2017-05-22T18:47:03.693Z",
"id": "59232fc9cfb4f8126c101548"
}

Request

Set transactional to false and provide an inMemberOf value to adhere to the subscribers preferences.

{
    "transactional": false,
    "updateProfile": false,
    "content": {
        "templateId": "1465362"
    },
    "recipients": [
        {
            "email": "jerry.garcia@yesmail.com",
            "id": "jerry.garcia@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "Garcia"
                    },
                    {
                        "firstName": "Jerry"
                    }
                ]
            },
            "subscriptions": {
                "isMemberOf": [
                    "Banjo Lovers"
                ]
            }
        }
    ]  
}

Response

The initial response includes the Ticket response. The content location in the header or the id value in the response body can be used to look up the final request status.

{
    "events": [
        {
            "message": "Send email request queued successfully.",
            "state": "accepted",
            "time": "2014-08-22T23:09:33.340Z"
        }
    ],
    "id": "53f7cdad3f3e5a25780c5be8",
    "lastUpdate": "2014-08-22T23:09:33.340Z",
    "message": "Send email request queued successfully.",
    "request": {
        "id": "ad60d17a-776c-41a9-9dd5-f023cf8ae93c",
        "time": "2014-08-22T23:09:33.000Z",
        "uri": "https://api.yesmail.com/v2/emails/send",
        "user": "adaptivemarketing"
    },
    "response": null,
    "state": "accepted"
}

Failed subscription check. If the recipient is not a member of the division specified the request will immediately fail with a 409 response code.

{
    "status": 409,
    "message": "Subscriber must be a memberOf one of '[Banjo Lovers]'."
}

Request

When updateProfile is set to false, the profile values are not stored, but can be used in message personalization. Use this to include HTML for product purchase or shipments.

{
    "transactional": true,
    "updateProfile": false,
    "content": {
        "templateId": "1460611"
    },
    "recipients": [
        {
            "email": "jerry.garcia@yesmail.com",
            "id": "jerry.garcia@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "Order Id": "PO611"
                    },
                    {
                        "Order Description": "<p>Thanks for your purchase. Please review your order and contact us immediately if there are any errors with your request.</p><a href="www.banjo.com/my_order"><img src="12string.png" /></a>"
                    }
                ]
            }
        }
    ]  
}

Response

Ticket response when the request included a response reference and URI parameter.

{
    "state": "accepted",
    "message": "Send email request queued successfully.",
    "request": {
        "id": "2c060779-4914-43b7-bdb5-51a9a958fbab",
        "user": "jefftronics3",
        "time": "2015-03-05T00:10:30.000Z",
        "uri": "https://api.yesmail.com/v2/emails/send?responseRef=PO611&responseUri=http%3A%2F%2Frequestb.in%2Fpd212hpd"
    },
    "response": {
        "uri": "http://requestb.in/pd212hpd",
        "ref": "PO611",
        "time": null,
        "code": null,
        "location": null,
        "data": null
    },
    "id": "54f79ef6907203387420efd9",
    "events": [
        {
            "state": "accepted",
            "message": "Send email request queued successfully.",
            "time": "2015-03-05T00:10:30.540Z"
        }
    ],
    "lastUpdate": "2015-03-05T00:10:30.540Z"
}

Completed request.

{
    "state": "completed",
    "message": "Send email request completed.",
    "request": {
        "id": "2c060779-4914-43b7-bdb5-51a9a958fbab",
        "user": "jefftronics3",
        "time": "2015-03-05T00:10:30.000Z",
        "uri": "https://api.yesmail.com/v2/emails/send?responseRef=PO611&responseUri=http%3A%2F%2Frequestb.in%2Fpd212hpd"
    },
    "response": {
        "uri": "http://requestb.in/pd212hpd",
        "ref": "PO611",
        "data": {
            "messageId": "905751723133",
            "sentTime": "2015-03-05T00:10:31.283Z"
        }
    },
    "events": [
        {
            "state": "accepted",
            "message": "Send email request queued successfully.",
            "time": "2015-03-05T00:10:30.540Z"
        },
        {
            "state": "completed",
            "message": "Send email request completed.",
            "time": "2015-03-05T00:10:31.288Z"
        }
    ],
    "lastUpdate": "2015-03-05T00:10:31.288Z",
    "id": "54f79ef6907203387420efd9"
}

Request

Use setReferred subscription parameter when building forms to send 3rd party emails to multiple people. This will send the message and set recipients as referred for reporting purposes.

{
    "content": {
        "templateId": "1465362"
    },
    "updateProfile": true,
    "transactional": true,
    "forwarder": {
        "id":"bill.graham@yesmail.com",
        "note":"Guys, check out this new concert venue I found in San Francisco. Bill."
        },
    "recipients": [
        {
            "email": "mickey.hart@yesmail.com",
            "id": "mickey.hart@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "Mickey"
                    },
                    {
                        "firstName": "Hart"
                    },
                    {
                        "Date of Birth": "1943-09-11"
                    }
                ]
            },
            "subscriptions": {
                "setReferred": "newOrNotSubscribed"
            }
        },
        {
            "email": "phil.lesh@yesmail.com",
            "id": "phil.lesh@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "Phil"
                    },
                    {
                        "firstName": "Lesh"
                    },
                    {
                        "Date of Birth": "1943-09-11"
                    }
                ]
            },
            "subscriptions": {
                "setReferred": "newOrNotSubscribed"
            }
        },
        {
            "email": "bob.weir@yesmail.com",
            "id": "bob.weir@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "Bob"
                    },
                    {
                        "firstName": "Weir"
                    },
                    {
                        "Date of Birth": "1943-09-11"
                    }
                ]
            },
            "subscriptions": {
                "setReferred": "newOrNotSubscribed"
            }
        },
        {
            "email": "bill.kreutzmann@yesmail.com",
            "id": "bill.kreutzmann@yesmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "Bill"
                    },
                    {
                        "firstName": "Kreutzmann"
                    },
                    {
                        "Date of Birth": "1946-05-07"
                    }
                ]
            },
            "subscriptions": {
                "setReferred": "newOrNotSubscribed"
            }
        }
    ]
}

Response

Since there were multiple recipients the Tickets response payload includes an Asynchronous results location.

{
    "state": "completed",
    "message": "Send email request completed.",
    "request": {
        "id": "30003c7e-87e1-412a-81e7-dd51e3bece4d",
        "user": "jefftronics3",
        "time": "2015-03-06T00:23:57.000Z",
        "uri": "https://api.yesmail.com/v2/emails/send"
    },
    "events": [
        {
            "state": "accepted",
            "message": "Send email request queued successfully.",
            "time": "2015-03-06T00:23:57.417Z"
        },
        {
            "state": "processing",
            "message": "update Ticket for AsyncResult info",
            "time": "2015-03-06T00:23:57.439Z"
        },
        {
            "state": "completed",
            "message": "Send email request completed.",
            "time": "2015-03-06T00:24:08.425Z"
        }
    ],
    "lastUpdate": "2015-03-06T00:24:08.425Z",
    "id": "54f8f39d3f3e5a257821ca01",
    "response": {
        "location": "https://api.yesmail.com/v2/async-results/54f8f39de4b0896dc35e0018"
    }
}

The asynchronous results where completed=true parameter is used.

{
    "id": "54f8f39de4b0896dc35e0018",
    "lastUpdated": "2015-03-05T16:23:58.583-08:00",
    "counts": {
        "requested": 4,
        "total": 4,
        "completed": 4,
        "ignored": 0,
        "failed": 0
    },
    "completed": [
        {
            "index": 3,
            "time": "2015-03-05T16:23:58.530-08:00"
        },
        {
            "index": 0,
            "time": "2015-03-05T16:23:58.531-08:00"
        },
        {
            "index": 1,
            "time": "2015-03-05T16:23:58.576-08:00"
        },
        {
            "index": 2,
            "time": "2015-03-05T16:23:58.570-08:00"
        }
    ],
    "failed": [],
    "ignored": []
}