Email

HiveSocial platform has the ability to sent emails on many occasions, managed by the user from its notification screen. All these emails are part of the email content item and you can manage them with the methods below.

If you are not using a third party SMTP server settings, but the local web server to send your emails you need to check some mail settings. In order to comply with the spam filters of the recipient mail servers you should make sure that:

  • In your system settings, set a "default administrator's email" with one, which has a domain name authorizing this server for sending emails. This email will appear as FROM field for all emails sent by the system.
  • To authorize the server, you have to add in your domain zone a TXT record allowing your local server to send emails on behalf of the FROM email's domain. The record contents for the IP 111.111.111.111 for example are v=spf1 ip4:111.111.111.111 ~all
  • Contact your server internet provider to create a "back resolve" for the server's IP with the FROM's email domain

Method: list

Authorization is required.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/email/sent/list?offset={offset}&pageSize={pageSize}&filter={filter}&target={target}&state={state}&startDate={startDate}&endDate={endDate}

Parameters

propertyvaluedescription
offset integer Needed for the infinite scroll functionality. It is the ID of the last presented item to the user. After the request list is generated the system will skip all records from the beginning up to the record with the provided ID (including it). The next batch of records will be returned in the response.
pageSize integer How many records to be returned by the system. Usually 15
filter string Query string to be looked for when filtering the records
target string In what type of data to look for the filter string. The alternatives are:
  • 0 - All types of data
  • to - Only in the email's "To" data
  • from - Only in the email's "From" data
  • subject - Only in the email's "Subject" data
  • content - Only in the email's "Content" data
state integer The current email state. The alternatives are:
  • 0 - All states
  • 1 - Only successfully send emails
  • 2 - Only failed emails
startDate date Email list is filtered also by period of the send date. This parameter represents this period start Date
endDate date Email list is filtered also by period of the send date. This parameter represents this period end Date

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "success": true,
  "message": "Laborum magna dolore excepteur irure eu.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": [],
  "object": {
    "offset": "a7c874f1-c2dd-4b5c-b7c1-758addd0a037",
    "emails": [
      {
        "id": "3BCB2CD8-9A58-41F8-B1D1-0811F5F9833D",
        "type": "email",
        "fromEmail": "test@hivesocial.com",
        "fromName": "HiveSocial support",
        "toEmail": "test2@hivesocial.com",
        "replyToEmail": "test@hivesocial.com",
        "subject": "Stet clita kasd gubergren no",
        "content": "Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit.",
        "sendOn": "2014-03-03T23:20:23Z",
        "stateId": 2,
        "stateName": "Failed",
        "errorMessage": "at System.Net.Mail.SmtpClient.Send(MailMessage message)nat BTWF.Client.Components.Scheduler.MailSenderTask.Execute(ThreadPool tp) in c:\\source\\HS4\\Libraries\\BTWF.Client\\Components\\Scheduler\\MailSenderTask.cs:line 228",
        "accessWarnings": []
      }
    ]
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
id guid The email's Id
fromEmail string The email of the sender. This email is configured in the system settings as the Default Administrator's email ("defaultAdministratorEmail" property).
fromName string The name that should appear in the From field. The system automatically sets this to the related user's alias if there is such relation.
toEmail string The receiving email
replyToEmail string When the recipient hits the reply button if its email client, to which email the reply needs to go.
subject string The emails subject
content string The email's body
sendOn date When the email was send in ISO 8601 format string and UTC time zone
stateId integer The current email state. The alternatives are:
  • 0 - All states
  • 1 - Only successfully send emails
  • 2 - Only failed emails
stateName string Human readable state. The alternatives are presented above.
errorMessage string If an error message was returned by the SMTP server, it will be stored here.

Method: pending list

Authorization is required. This list represents all emails that are not yet send.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/email/pending/list?offset={offset}&pageSize={pageSize}

Parameters

propertyvaluedescription
offset integer Needed for the infinite scroll functionality. It is the ID of the last presented item to the user. After the request list is generated the system will skip all records from the beginning up to the record with the provided ID (including it). The next batch of records will be returned in the response.
pageSize integer How many records to be returned by the system. Usually 15

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "success": true,
  "message": "Laborum magna dolore excepteur irure eu.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": [],
  "object": {
    "offset": "a7c874f1-c2dd-4b5c-b7c1-758addd0a037",
    "emails": [
      {
        "id": "3BCB2CD8-9A58-41F8-B1D1-0811F5F9833D",
        "type": "email",
        "fromEmail": "test@hivesocial.com",
        "fromName": "HiveSocial support",
        "toEmail": "test2@hivesocial.com",
        "replyToEmail": "test@hivesocial.com",
        "subject": "Stet clita kasd gubergren no",
        "content": "Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper.",
        "sendOn": null,
        "stateId": null,
        "stateName": null,
        "errorMessage": null,
        "accessWarnings": []
      }
    ]
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
id guid The email's Id
fromEmail string The email of the sender. This email is configured in the system settings as the Default Administrator's email ("defaultAdministratorEmail" property).
fromName string The name that should appear in the From field. The system automatically sets this to the related user's alias if there is such relation.
toEmail string The receiving email
replyToEmail string When the recipient hits the reply button if its email client, to which email the reply needs to go.
subject string The emails subject
content string The email's body
sendOn date It is null in this list as the emails are not send yet.
stateId integer It is null in this list as the emails are not send yet.
stateName string It is null in this list as the emails are not send yet.
errorMessage string It is null in this list as the emails are not send yet.

Method: resend

Authorization is required. Send an email again.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/email/sent/{emailId}/resend

Parameters

propertyvaluedescription
emailId guid The Id of the email that you need to resend

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "timestamp": "2014-03-03T23:20:23Z",
  "success": true,
  "message": "The announcement was not created. Validation error occured!",
  "errors": [],
  "object": {
    "id": "3BCB2CD8-9A58-41F8-B1D1-0811F5F9833D",
    "type": "email",
    "fromEmail": "test@hivesocial.com",
    "fromName": "HiveSocial support",
    "toEmail": "test2@hivesocial.com",
    "replyToEmail": "test@hivesocial.com",
    "subject": "Stet clita kasd gubergren no",
    "content": "Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper.",
    "sendOn": "2014-03-03T23:20:23Z",
    "stateId": 2,
    "stateName": "Failed",
    "errorMessage": "at System.Net.Mail.SmtpClient.Send(MailMessage message)nat BTWF.Client.Components.Scheduler.MailSenderTask.Execute(ThreadPool tp) in c:\\source\\HS4\\Libraries\\BTWF.Client\\Components\\Scheduler\\MailSenderTask.cs:line 228",
    "accessWarnings": []
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
success Boolean Whether the requested operation is successful or not on HiveSocial software level
message String Human readable error information provided by HiveSocial (the smtp server error is provided in the object's errorMessage property)
object object The current state of the email object.