Class EmailsApiV2Controller
Class EmailsApiV2Controller
This controller provides a gateway to the EmailService of the system. The user is able to get, send, queue
and delete email records through his shop. Email forwarding is not directly supported but can be easily
implemented by getting an existing email and then sending it with the updated contact addresses.
API consumers can also upload attachments through the AttachmentsApiV2Controller and later use them within
their emails. The upload operation must be executed before sending/queuing the email because it is not possible
to send the email JSON data and upload a file at the same time. For more info see the AttachmentsV2Controller.
-
AbstractApiV2Controller
-
┗
HttpApiV2Controller
-
┗
EmailsApiV2Controller
Methods summary
protected
__initialize( void )
Initialize controller components.
Initialize controller components.
public
post( void )
Api
{post} /emails/:id Send Email
Apidescription
This method will send and save a new or an existing email to the system. If you include mail attachments
then they must already exist in the server. You will need to provide the full path to the file. To see an
example usage take a look at
docs/REST/samples/email-service/send_email.php
Apierror
400-BadRequest Email data were not provided.
404-NotFound Email record was not found.
Apierrorexample
Error-Response (400)
HTTP/1.1 400 Bad Request
{
"code": 400,
"status": "error",
"message": "Email data were not provided."
}
Error-Response (404)
HTTP/1.1 404 Not Found
{
"code": 404,
"status": "error",
"message": "Email record was not found."
}
Apigroup
Emails
Apiname
SendEmail
Apiparam
{Number} [id] If provided then an existing email will be resend (only applies to URL).
{String} [subject] Email subject to be sent.
{Object} sender Contains the sender contact data.
{String} sender.emailAddress Sender's email address.
{String} [sender.contactName] Sender display name.
{Object} recipient Contains the recipient contact data.
{String} recipient.emailAddress Recipient's email address.
{String} [recipient.contactName] Recipient's display name.
{Object} replyTo Contains the reply to contact data.
{String} replyTo.emailAddress Email address of the 'Reply-To' contact.
{String} replyTo.contactName Name of the 'Reply-To' contact.
{String} [contentHtml] Email plain content.
{String} [contentPlain] Email HTML content.
{Array} [bcc] Contains the BCC contacts of the email.
{Array} [cc] Contains the CC contacts of the email.
{Array} [attachments] Contains the attachment data.
{String} attachments[].path The path to the attachments (the file must already exist in the server).
{String} [attachments[].name] Set a display name for the attachment file (must also contain
the file extension).
Apiparamexample
{json} Request-Body
{
"subject": "Test Subject",
"sender": {
"emailAddress": "sender@email.de",
"contactName": "John Doe"
},
"recipient": {
"emailAddress": "recipient@email.de",
"contactName": "Jane Doe"
},
"replyTo": {
"emailAddress": "reply_to@email.de",
"contactName": "John Doe (Reply To)"
},
"contentHtml": "HTML Content",
"contentPlain": "Plain Content",
"bcc": [
{
"emailAddress": "bcc@email.de",
"contactName": "Chris Doe"
}
],
"cc": [
{
"emailAddress": "cc@email.de",
"contactName": "Chloe Doe"
}
],
"attachments": [
{
"path": "/var/www/html/shop/uploads/attachments/1434614398/myfile.txt",
"name": "Display For MyFile.txt"
}
]
}
Apisuccess
(Success 201) Response-Body If successful, this method returns a complete email resource in the
response body.
Apiversion
2.1.0
public
put( void )
Api
{put} /emails Queue Email
Apidescription
This method will queue a new email so that it can be send later (with the POST method). See
the "post" method for parameter description. To see an example usage take a look at
docs/REST/samples/email-service/queue_email.php
Apierror
400-BadRequest Email data were not provided.
Apierrorexample
Error-Response
HTTP/1.1 400 Bad Request
{
"code": 400,
"status": "error",
"message": "Email data were not provided."
}
Apigroup
Emails
Apiname
QueueEmail
Apisuccess
(Success 200 - Email Was Queued) {String} Response-Body If successful, this
method returns a complete email resource in the response body.
Apiversion
2.1.0
public
delete( void )
Todo
Do not throw an error if a record does not exist. Because this is what other controllers do.
Api
{delete} /emails/:id Delete Email
Apidescription
Delete an email record from database. To see an example usage take a look at
docs/REST/samples/email-service/remove_email.php.
Apierror
400-BadRequest The email ID parameter is missing or is not valid.
Apiexample
{curl} Delete Email with ID = 572
curl -X DELETE --user admin@shop.de:12345 http://shop.de/api.php/v2/emails/572
Apigroup
Emails
Apiname
DeleteEmail
Apisuccess
Response-Body If successful this method returns information about the deleted record.
Apisuccessexample
{json} Success-Response
{
"code": 200,
"status": "success",
"action": "delete",
"emailId": 73
}
Apiversion
2.1.0
public
get( void )
Api
{get} /emails/:id Get Emails
Apidescription
Get multiple or a single email record through the GET method. This resource supports
the following GET parameters as described in the first section of documentation: sorting
minimization, search, pagination. Additionally you can filter emails by providing the
GET parameter "state=pending" or "state=sent". These filter parameters do not apply when
a single emails record is selected (e.g. api.php/v2/emails/84) or when the emails are searched
by the "q" parameter. To see an example usage take a look at
docs/REST/samples/email-service/fetch_email.php
Apierror
404-NotFound Email record not found.
Apierrorexample
Error-Response
HTTP/1.1 404 Not Found
{
"code": 404,
"status": "error",
"message": "Email record could not be found."
}
Apiexample
{curl} Get All Emails
curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/emails
{curl} Get Email With ID = 527
curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/emails/527
{curl} Get Pending Emails
curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/emails?state=pending
{curl} Search Emails
curl -i --user admin@shop.de:12345 http://shop.de/api.php/v2/emails?q=admin@shop.de
Apigroup
Emails
Apiname
GetEmails
Apiversion
2.1.0
_linkResponse(),
_locateResource(),
_mapResponse(),
_minimizeResponse(),
_paginateResponse(),
_searchResponse(),
_setJsonValue(),
_sortResponse(),
_writeResponse()
__construct(),
_prepareResponse(),
_setRateLimitHeader(),
_validateRequest()
Constants summary
DEFAULT_CONTROLLER_NAME,
DEFAULT_PAGE_ITEMS,
DEFAULT_RATE_LIMIT,
DEFAULT_RATE_RESET_PERIOD
Properties summary
$api,
$uri