getPendingEmails — Retrieving pending emails

The getPendingEmails method retrieves the ID and metadata of messages queued for display in the SiteLock dashboard’s Messages section. The response returns a list of pending in-dashboard messages based on the specified criteria you may have specified.

The API endpoint is:

https://api.sitelock.com/v1/partner

Request format

SiteLockOnlineRequest: This element is used to delineate the full API request.

authentication: The partner’s username, password, and branding
- username: The partner’s API username
- password: The partner’s API password
- partner: (Optional) The brand name to use in messaging

getPendingMessages: The method name

before: (Optional) If specified, only messages from before this date are returned.
after: (Optional) If specified, only messages from after this date are returned.

account: (Optional) If specified, only messages for this account ID are returned.

The before and after attributes must be specified in the format YYYY-MM-DD HH:MM:SS, where years are always four digits, all other fields are two digits, and always include a leading zero for single-digit values. Dates not meeting this criteria or dates that cannot be validated will be silently rejected.

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>password</password>
    </authentication>
    <getPendingEmails>
        <before>2012-01-15 06:00:00</before>
        <after>2011-12-25 18:00:00</after>
        <account>234</account>
    </getPendingEmails>
</SiteLockOnlineRequest>

Response format

SiteLockOnlineResponse: This element is used to delineate the full API response.

getPendingEmails: The method name

status: Either success or failed
error: The error message if status is failed

emails: A list of messages

email: (Repeatable) A message

email_address: The user’s email address
domain: The site to which this message relates
email_id: Contains the value 20, which indicates a message for the user
queue_id: A unique instance identifier. Use it in your call to markEmailSent.
queue_time: The timestamp when the email was queued
account_id: The SiteLock account ID of the user

replacements: The two types of main subelements

The following is a set of user-specific elements that is always sent with each response.

name: The name of the user
host: The same as domain
lang_id: The preferred language of the user
to: The email address of the user

MessageText: The content shown in the SiteLock dashboard’s "Messages" section, which includes all the necessary details. It’s a record of the message for reference. The original template for this message can be found in the defaultCopy section of the getMessageTypesresponse.

The following is a set of message metadata elements that is always sent with each response. This data that is also available in the output from getMessageTypes. Distinct metadata values can be obtained from the getMessageTypes response.

MessageId: A reference to an individual message from getMessageTypes
MessageCode: The message code
type: The message type/category
severity: The message severity

Dynamic child elements: Dynamic child elements

The dynamic child elements are provided for informational purposes only. Partners shouldn’t rely on their continued presence. These elements may be replaced or removed as SiteLock revises its workflows and email templates.

Each of these child elements denotes a message placeholder.
The element name directly corresponds to the placeholder text in the template.
The element’s value is the expression that needs to be substituted into the template in place of the placeholder text.
for example, the existence of <site>example.org</site> means that somewhere in the template for this message, the placeholder \{\{--site--}} exists, which should be replaced with the expression example.org
To determine the possible dynamic elements for a message, see the defaultCopy element in the output from getMessageTypes All placeholder text looks like \{\{--XXXXX--}} where XXXXX is the substitution value, such as site in the above example.
These placeholder substitution elements are sent based on the assumption that our partner sends copy that is similar to SiteLock’s copy. If your copy doesn’t include any placeholder text, or you’re using your own set of placeholders distinct from SiteLock’s placeholders, then you can safely ignore this dynamic set.

Example success response

<SiteLockOnlineResponse>
    <getPendingEmails>
        <status>success</status>
        <emails>
            <email>
                <email_address>[email protected]</email_address>
                <domain>example.com</domain>
                <email_id>20</email_id>
                <replacements>
                    <SupportPhone>000-555-1212</SupportPhone>
                    <_lang_id>1</_lang_id>
                    <system_email_id>78</system_email_id>
                    <_MessageId>100</_MessageId>
                    <to>[email protected]</to>
                    <domain>example.com</domain>
                    <support_phone>1-000-555-1212</support_phone>
                    <severity>critical</severity>
                    <brand_name>Doe Web Hosting</brand_name>
                    <name>John</name>
                    <prompts>11</prompts>
                    <prompt_files>11</prompt_files>
                    <MessageText>Your SMART scanner has been hard at work! During a recent scan, it found some malware and automatically removed it from your website.
                    We are happy to report that your site is now clean and malware-free.</MessageText>
                    <changed>2</changed>
                    <site>example.com</site>
                    <_MessageCode>smart-mal-fixed</_MessageCode>
                    <cleaned>1</cleaned>
                    <type>security</type>
                    <Name>John</Name>
                </replacements>
                <queue_id>1234567</queue_id>
                <queue_time>2020-05-05 07:25:00</queue_time>
                <account_id>987655555</account_id>
            </email>
        </emails>
    </getPendingEmails>
</SiteLockOnlineResponse>

Example error response

<SiteLockOnlineResponse>
    <getPendingEmails>
        <error>No Messages</error>
        <status>failed</status>
    </getPendingEmails>
</SiteLockOnlineResponse>

Error codes

Partner not configured for white label email access
No Messages