REST Newsletter

List, create, update and delete newsletter entries, newsletter folders and recipients that are assigned to a newsletter folder.

List newsletter entries

/rest/newsletters

Success 200

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the newsletter entry

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List details of an entry

Lists details of an entry. The ID of the entry must be specified.

/rest/newsletters/{entryId}

Parameters

Field Type Description
entryId Int The ID of the newsletter entry.

Success 200

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the newsletter entry
{"id":2,"subject":"Disposition","body":"Hello [NAME], find our latest dispositions","kind":"plain"}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List newsletter folders

/rest/newsletters/folders

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List details of a folder

Lists details of a folder. The ID of the folder must be specified.

/rest/newsletters/folders/{folderId}

Parameters

Field Type Description
folderId Int The ID of the newsletter folder.

Success 200

Field Type Description
id Int The ID of the newsletter folder
name String The name of the newsletter folder
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
position Int The position of the newsletter folder
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If this is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.
{"id":1,"name":"Customer","isDeleteable":0,"position":0,"isSelectable":0,"clients":{"id":1337}}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List all recipients of a folder

Lists all recipients of a folder. The ID of the folder must be specified.

/rest/newsletters/folders/{folderId}/recipients

Parameters

Field Type Description
folderId Int The ID of the newsletter folder.

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List recipients of a folder

/rest/newsletters/recipients

Parameters

Field Type Description
email String Filter that restricts the search result to the email address of the recipient
folderId Int Filter that restricts the search result to the folder ID
recipientId Int Filter that restricts the search result to the recipient ID

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List recipients

/rest/newsletters/list_recipients

Parameters

Field Type Description
columns String[] Filter that restricts the search result to specific columns
page Int The page to get. The default page that will be returned is page 1.
itemsPerPage Int The number of orders to be displayed per page. The default number of orders per page is 50.
folderId Int Filter that restricts the search result to a specific folderId.
isConfirmed Bool Filter that restricts the search result to confirmed recipients.
with String[] Load additional relations for a Recipient. CURRENTLY NOT AVAILABLE

Success 200

Field Type Description
page Int Current page of the response
totalsCount Int The total number of entries in the response
isLastPage Bool Flag that indicates if the page shown is the last page of the response
lastPageNumber Int The last page number
firstOnPage Int The index of the first item of the current page result
lastOnPage Int The index of the last item of the current page result
itemsPerPage Int The requested amount of items per result page
entries Array List

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List a recipient

Lists a recipient. The ID of the recipient must be specified.

/rest/newsletters/recipients/{recipientId}

Parameters

Field Type Description
recipientsId Int The ID of the newsletter folder.

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter
{"id":57,"folderId":1,"contactId":13,"firstName":"John","lastName":"Doe","email":"john@account.com","gender":"m","birthday":"1984-03-19","timestamp":"2017-05-11 09:55:22","templateLang":"de","confirmedTimestamp":"2017-05-11 10:55:00"}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Create an entry

/rest/newsletters

Parameters

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the entry. The content can be saved as plain text or in HTML format. Possible values: ['plain', 'html'].

Request

Field Type Description
subject String The subject of the newsletter entry required
body String The body of the newsletter entry optional
kind String The type of the newsletter entry optional
{"subject":"Sales","body":"Hello [NAME], find our latest sales","kind":"plain"}

Success 200

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the newsletter entry

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Create a folder

/rest/newsletters/folders

Parameters

Field Type Description
id Int The ID of the newsletter folder
name String The name of the newsletter folder
position Int The position of the newsletter folder
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. Default value of is deletable is 1. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If it is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.

Request

Field Type Description
id Int The ID of the newsletter folder optional value must be unique
name String The name of the newsletter folder required
position Int The position of the newsletter folder optional
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted. optional
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If this is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder. optional
{"id":1,"name":"Warm Leads","position":0,"isDeletable":true,"isSelectable":false}

Success 200

Field Type Description
id Int The ID of the newsletter folder
name String The name of the newsletter folder
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
position Int The position of the newsletter folder
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If this is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Create a recipient

/rest/newsletters/recipients

Parameters

Field Type Description
email String The email address of the recipient
firstName String The first name of the recipient
lastName String The last name of the recipient
folderIds String[] The IDs of the newsletter folders. These folders were selected by the customer in the online store in order to receive newsletters included in these folders.
isFrontend Bool Value that indicates if the REST call was retrieved from the front end. Possible values are: 'true' or 'false'. True = The REST call was retrieved from the front end. False = The REST call was not retrieved from the front end.
ignoreVisibility Bool Value that indicates if the REST call considers folders without visibility. Possible value: 'true'. If the value 'true' is set, the folder visibility will be ignored. This means that both visible and invisible folders will be listed depending on the folder IDs entered in the REST call.
ipAddress String The IP address from where the customer has confirmed the newsletter

Request

Field Type Description
email String The email address of the recipient required
{"email":"john@account.com","firstName":"John","lastName":"Doe","gender":"m","timestamp":"2017-05-11 09:55:22","confirmedTimestamp":"2017-05-11 10:55:00","folderIds":[1],"isFrontend":false}

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Update an entry

Updates an entry. The ID of the entry must be specified.

/rest/newsletters/{entryId}

Parameters

Field Type Description
subject String The subject of the entry
body String The body of the entry
kind String The type of the entry. The content can be saved as plain text or in HTML format. Possible values: ['plain', 'html'].

Success 200

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the newsletter entry
{"subject":"New Customers","body":"Hello [NAME], find our latest sales","kind":"plain"}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Update a folder

Updates a folder. The ID of the folder must be specified.

/rest/newsletters/folders/{folderId}

Parameters

Field Type Description
name String The name of the newsletter folder
position Int The position of the newsletter folder
clientIds String[] The IDs of the clients (stores). It is possible to determine which clients (stores) the newsletter folder is visible for.
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If it is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.

Success 200

Field Type Description
id Int The ID of the newsletter folder
name String The name of the newsletter folder
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
position Int The position of the newsletter folder
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If this is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.
{"id":10,"name":"Warm Leads","isDeleteable":0,"position":0,"isSelectable":false,"clients":[]}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Update a recipient

Updates a recipient that is assigned to a folder. The ID of the recipient must be specified.

/rest/newsletters/recipients/{recipientId}

Parameters

Field Type Description
email String The email address of the newsletter recipient
firstName String The first name of the newsletter recipient
lastName String The last name of the newsletter recipient
folderIds String[] DEPRECATED: The IDs of the newsletter folders. These folders were selected by the customer in the online store in order to receive newsletters included in these folders.
folderId Int The ID of the newsletter folder.
ipAddress String The IP address from where the customer has confirmed the newsletter
birthday String The customer birthday as Date string (e.g. '1982-11-24', '1982/11/24' or '24.11.1982')
gender String The gender of the customer, one of the following values: 'm','f'.

Request

Field Type Description
email String The email address of the recipient required
{"email":"john.doe@account.com","firstName":"John","lastName":"Doe","folderIds":[1,2]}

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter
{"id":57,"folderId":1,"contactId":13,"firstName":"John","lastName":"Doe","email":"john.doe@account.com","gender":"m","birthday":"1984-03-19","timestamp":"2017-05-11 09:55:22","templateLang":"de","confirmedTimestamp":"2017-05-11 10:55:00"}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete entries

/rest/newsletters

Success 200

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the newsletter entry

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete an entry

Deletes an entry. The ID of the entry must be specified.

/rest/newsletters/{entryId}

Success 200

Field Type Description
subject String The subject of the newsletter entry
body String The body of the newsletter entry
kind String The type of the newsletter entry

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete folders

/rest/newsletters/folders

Success 200

Field Type Description
id Int The ID of the newsletter folder
name String The name of the newsletter folder
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
position Int The position of the newsletter folder
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If this is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete a folder

Deletes a folder. The ID of the folder must be specified.

/rest/newsletters/folders/{folderId}

Success 200

Field Type Description
id Int The ID of the newsletter folder
name String The name of the newsletter folder
isDeletable Bool Flag that indicates if the newsletter folder can be deleted. The folders 'Customers' and 'Interested parties' are available by default and cannot be deleted.
position Int The position of the newsletter folder
isSelectable Bool Flag that indicates if the newsletter folder can be selected by customers in the online store. If this is allowed, the folder will be displayed in the My account area of the online store. Customers will then be able to subscribe to the newsletters that are included in this folder.

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete recipients

/rest/newsletters/recipients

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete a recipient

Deletes a recipient. The ID of the recipient must be specified.

/rest/newsletters/recipients/{recipientId}

Success 200

Field Type Description
id Int The ID of the newsletter recipient
folderId Int The ID of the newsletter folder
contactId Int The ID of the contact
firstName String The first name of the recipient
lastName String The last name of the recipient
email String The email address of the recipient
gender String The gender of the recipient
birthday String The birthday of the recipient
timestamp Int The timestamp when the newsletter email was sent to the recipient
templateLang String The language of the newsletter email template
confirmedTimestamp Int The timestamp when the recipient confirmed the newsletter subscription
confirmAuthString String The key that is automatically generated by the system. This key recognises the user regardless whether the user is logged in to the system and will then set the confirmation timestamp.
confirmationURL String The url with which the customer has confirmed the newsletter

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

/rest/newsletters/double_opt_in/{contactId}

Success 200

Field Type Description
contentType String response content type
contentLength Int response content length
content String response content

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Is this article helpful?

 

Thank you for your Feedback

you can close this field now!