REST API

Legacy Poppulo platform REST API

Mailing

Overview

This is a Mailing. It is the result of submitting a Mail Job entity. It contains information about how the mailing was specified, and also the results of the mailing. The entity has a status attribute, indicating if it is ongoing or finished.

Scheduled mailings

Mail jobs that were submitted for processing at a later date/time will have a status "Scheduled" until that time.

Mailings in progress

The mailing will have the status attribute set to CurrentlyExecuting in this state. The progress sub-tag of this entity is output while the mailing is running. The information here can be used to build a progress bar. The ping_after field represents the time you should wait before polling again. Failing to observe this recommendation can result in rate limiting responses being returned.

Completed

Mailings that complete successfully will have Completed as their status attribute. Mailings that fail will have CompletedWithErrors as their status attribute.

Suspended and Cancelled mailings

A mailing can be suspended or cancelled using the Poppulo Web Application. Please note that there is no way to cancel or suspend a mailing using this API. Mailings will have a status of Suspended, ScheduledSuspended or Cancelled in such cases.

Attributes

Name	Description	Type
`status`	The current status of the mailing, as described above	Enumeration of `Scheduled`, `CurrentlyExecuting`, `Completed`, `CompletedWithErrors`, `Suspended`, `ScheduledSuspended`, `Cancelled`.

Organisational Elements

A mailing entity is made up of two important sub-elements.

The progress element:

Progress Fields

Field name	Description	Type/Allowed values
`total_emails`	The number of subscribers matched by the mailing target(s)	Number
`emails_dispatched`	The number of emails that have been sent and are making their way to the subscriber's inboxes	Number
`ping_after`	The next time the client should request the current mailing state	Date

The specification element. The meaning of the tags is identical to those in the Mail Job Entity.

Examples

<mailing status="Completed" type="test" uri="https://api.newsweaver.com/v2/example-account/mailing/1234">
    <progress>
        <total_emails>1</total_emails>
        <emails_dispatched>1</emails_dispatched>
    </progress>

    <specification>
        <send_datetime>2011-06-01T10:34:14Z</send_datetime>
        <subject>Hello, world</subject>
        <from_name>Joe Bloggs</from_name>
        <from_address>joe.bloggs@example.com</from_address>
        <format>SUBSCRIBER_PREFERENCE</format>
        <to>
            <target_type>testers</target_type>
            <targets>
                <target>Main Reviewers</target>
            </targets>
        </to>
        <respect_quota>true</respect_quota>
        <resend_if_received>false</resend_if_received>
    </specification>

    <link
        href="https://api.newsweaver.com/v2/example-account/issue/123"
        rel="http://api-info.newsweaver.com/v2/rels/mailing.issue"
        title="Issue (123)"/>
    <link
        href="https://api.newsweaver.com/v2/example-account/mailing/1234/activity_summary"
        rel="http://api-info.newsweaver.com/v2/rels/mailing.activity_summary"
        title="Mailing (1234) Activity Summary"/>
    <link
        href="https://api.newsweaver.com/v2/example-account/mailing/1234/content_popularity"
        rel="http://api-info.newsweaver.com/v2/rels/mailing.content_popularity"
        title="Mailing (1234) Content Popularity"/>
</mailing>

See calls: