REST API

Legacy Poppulo platform REST API

Mail Job

Overview

A mail job allows one to send emails to Subscribers. Each subscriber who is to receive an email must be associated with the appropriate Permissions. With that in mind, you can send to all eligible subscribers, or you can target sub-sets:

Target type	Description
`all_subscribers`	All subscribers will be matched. This option is only available for approved issues.
`tag`	Allows multiple tag names to be specified. Subscribers associated with any of the tags will be matched. This option is only available for approved issues.
`saved_search`	Subscribers are matched against the named saved search criteria. This option is only available for approved issues.
`testers`	All members of the named reviewer group will be matched. This email will be a test email. This option can be used with draft and approved issues.
`email`	Send to a single email address: If the email address belongs to that of a reviewer, this email will be a test email. If the email address belongs to a subscriber who is not a reviewer, the email will be tracked. If the email address is not a subscriber, the email will not be tracked. Where possible, instead of sending the same email using this mechanism, consider using a tag, saved search or reviewer group instead. This option can be used with draft and approved issues. See the examples below to see how these are used. Sending a mailing causes a microsite to be published (or re-published). It is possible to personalize the emails your subscriber's receive, for example varying the subject line, "from" details or reply-to address using subscriber macros.

Fields

Field name	Description	Type/Allowed values
`format`	Use this to force the emails to be sent in HTML or plain text. By default, emails will be send in the subscriber's preferred format.	An enumeration of `HTML` or `TEXT` or `SUBSCRIBER_PREFERENCE`.
`subject`	The subject line the subscriber will see.	Text
`from_name`	The sender name the subscriber will see. If absent, the publication's default sender details will be used (if available).	Text
`from_address`	The sender email address the subscriber will see. If absent, the publication's default sender details will be used (if available).	Text
`send_datetime`	If specified, defer the mailing until that time. Can use symbolic time `NOW`. If absent, default is to send immediately	Date
`respect_quota`	If `true`, ensure that no overage is charged by limiting the total number of subscribers to your remaining email quota if necessary. Defaults to `false`.	Boolean
`resend_if_received`	If `true`, subscribers who have already received this issue are eligible to be matched and sent to again. TODO: What is default behaviour in relation to tests? Do not use this option without good reason.	Boolean
`target_type`	Determines how the `target` tags are interpreted.	Enumeration of `all_subscribers`, `tag`, `saved_search`, `testers`, `email_address`
`target`	The name of a particular target to match	Text

Examples

Simple example, sending an issue to be reviewed:

<mail_job>
    <subject>Please review me!</subject>
    <to>
        <target_type>testers</target_type>
        <targets>
            <target>Main Reviewers</target>
        </targets>
    </to>
</mail_job>

Sending to an individual reviewer to test the TEXT version of your email.

<mail_job>
    <subject>Please review our text email</subject>
    <format>TEXT</format>
    <to>
        <target_type>email_address</target_type>
        <targets>
            <target>content-reviewer@example.com</target>
        </targets>
    </to>
</mail_job>

Sending to a set of tags, prepared to incur overage charges:

<mail_job>
    <subject>Your weekly student newsletter</subject>
    <to>
        <target_type>tag</target_type>
        <targets>
            <target>Arts Students</target>
            <target>Science Students</target>
            <target>Business Students</target>
        </targets>
    </to>
    <respect_quota>false</respect_quota>
</mail_job>

Scheduling a send for later to all subscribers:

<mail_job>
    <send_datetime>2099-01-01T00:00:00Z</send_datetime>
    <subject>An e-blast from the past</subject>
    <to>
        <target_type>all_subscribers</target_type>
    </to>
</mail_job>

Complete example:

<mail_job>
    <send_datetime>NOW</send_datetime>
    <subject>...</subject>
    <from_name>...</from_name>
    <from_address>...</from_address>
    <reply_address>...</reply_address>
    <format>SUBSCRIBER_PREFERENCE|HTML|TEXT</format>
    <to>
        <target_type>all_subscribers|tag|saved_search|testers|email_address</target_type>
        <targets>
            <target>tag/saved search/test tag/email</target>
            <target>...</target>
        </targets>
    </to>
    <respect_quota>true|false</respect_quota>
    <resend_if_received>true|false</resend_if_received>
</mail_job>

Overview

Fields

Examples