Mail Job

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](/api-glossary/api-test-email.html).
  • 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>

results matching ""

    No results matching ""