Tutorial: Send a mass email Version 2

This tutorial demonstrates how to create, target, send a mass email, and view engagement statistics via the API, without using the user interface.

Steps:

Create a message

To create a message, POST to the messages collection. Make sure to include all of a message's required fields (subject, body, from, and reply_to), and optionally include any other fields, such as linked queries in the targets array to target your email to activists on your list who match certain queries, or links to an email wrapper to use.

Calling the POST endpoint using your preferred method of making API calls (curl, etc...) like this:

						
POST https://actionnetwork.org/api/v2/messages

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here
						

{	
  "identifiers": [
    "my_email_system:1"
  ],
  "subject": "Stop doing the bad thing",
  "body": "<p>The mayor should stop doing the bad thing.</p>",
  "from": "Progressive Action Now",
  "reply_to": "jane@progressiveactionnow.org",
  "targets": [
    {
      "href": "https://actionnetwork.org/api/v2/queries/2cba37d8-1fbf-11e7-8cc2-22000aedd9ed"
    }
  ],
  "_links": {
    "osdi:wrapper": {
      "href": "https://actionnetwork.org/api/v2/wrappers/c945d6fe-929e-11e3-a2e9-12313d316c29"
    }
  }
}

Will return a response like this:

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d",
    "my_email_system:1"
  ],
  "origin_system": "Action Network",
  "created_date": "2014-03-24T18:03:45Z",
  "modified_date": "2014-03-25T15:00:22Z",
  "subject": "Stop doing the bad thing",
  "body": "<p>The mayor should stop doing the bad thing.</p>",
  "from": "Progressive Action Now",
  "reply_to": "jane@progressiveactionnow.org",
  "administrative_url": "https://actionnetwork.org/emails/stop-doing-the-bad-thing/manage",
  "status": "calculating",
  "type": "email",
  "targets": [
    {
      "href": "https://actionnetwork.org/api/v2/queries/2cba37d8-1fbf-11e7-8cc2-22000aedd9ed"
    }
  ],
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
    },
    "osdi:wrapper": {
      "href": "https://actionnetwork.org/api/v2/wrappers/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "osdi:send_helper": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d/send"
    },
    "osdi:schedule_helper": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d/schedule"
    }
  }
}

You can see that the message was POSTed with a query in the targets array, causing it to be targeted to that query as an include. The message was immediately put into calculating status while the targeting was calculated.

The message was also POSTed with a link to a wrapper, so that wrapper was used for that message when the resource was returned.

You cannot send the email when it is calculating its targeting. Move on to the next step to continue with the sending process.

Back To Top ↑

Poll the message until targeting has finished

Because a message cannot be sent until targeting is calculated (an operation that can take several seconds or minutes, depending on the size of your list and complexity of your targeting), you should poll the GET endpoint of your message every so often so you can obvserve when targeting finishes and the email is put back into 'draft' status.

GETting the message's endpoint:

						
GET https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d

Header:
OSDI-API-Token: your_api_key_here

Will return a response like this:

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d"
  ],
  "origin_system": "Action Network",
  "created_date": "2014-03-24T18:03:45Z",
  "modified_date": "2014-03-25T15:00:22Z",
  "subject": "Stop doing the bad thing",
  "body": "<p>The mayor should stop doing the bad thing.</p>",
  "from": "Progressive Action Now",
  "reply_to": "jane@progressiveactionnow.org",
  "administrative_url": "https://actionnetwork.org/emails/stop-doing-the-bad-thing/manage",
  "total_targeted": 2354,
  "status": "daft",
  "type": "email",
  "targets": [
    {
      "href": "https://actionnetwork.org/api/v2/queries/2cba37d8-1fbf-11e7-8cc2-22000aedd9ed"
    }
  ],
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
    },
    "osdi:wrapper": {
      "href": "https://actionnetwork.org/api/v2/wrappers/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "osdi:send_helper": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d/send"
    },
    "osdi:schedule_helper": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d/schedule"
    }
  }
}

Once the message is in 'draft' status and it has a total_targeted count greater than 0, it can be sent to the activists targeted. Move on to the next step to send the message.

Back To Top ↑

Send the message

Once the message is in 'draft' status and it has a total_targeted count greater than 0, it can be sent to the activists targeted. Use the send helper link to send the message.

POSTing an empty JSON object to the message's send helper endpoint:

						
POST https://actionnetwork.org/api/v2/messages/9f837109-710d-442f-8a99-857a21f36d25/send/

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here
						

{}

Will return a response like this:

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate



{
  "message": "Your email has been sent."
}

Your email is now being sent to the activists targeted. You can now see the engagement statistics of that email as activists interact with it in the next step.

Back To Top ↑

View message engagement statistics

GET the message's endpoint again to see an updated message resource with statistics that represent how activists are engaging with your email, such as the number of opens, clicks, unsubscribes, and the like.

GETting the message's endpoint:

						
GET https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d

Header:
OSDI-API-Token: your_api_key_here

Will return a response like this:

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d"
  ],
  "origin_system": "Action Network",
  "created_date": "2014-03-24T18:03:45Z",
  "modified_date": "2014-03-25T15:00:22Z",
  "subject": "Stop doing the bad thing",
  "body": "<p>The mayor should stop doing the bad thing.</p>",
  "from": "Progressive Action Now",
  "reply_to": "jane@progressiveactionnow.org",
  "administrative_url": "https://actionnetwork.org/emails/stop-doing-the-bad-thing/manage",
  "total_targeted": 2354,
  "status": "sent",
  "sent_start_date": "2014-03-26T15:00:22Z",
  "type": "email",
  "targets": [
    {
      "href": "https://actionnetwork.org/api/v2/queries/2cba37d8-1fbf-11e7-8cc2-22000aedd9ed"
    }
  ],
  "statistics": {
    "sent": 2354,
    "opened": 563,
    "clicked": 472,
    "actions": 380,
    "action_network:donated": 14,
    "action_network:total_amount": 320.25,
    "unsubscribed": 12,
    "bounced": 2,
    "spam_reports": 1
  },
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
    },
    "osdi:wrapper": {
      "href": "https://actionnetwork.org/api/v2/wrappers/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "osdi:recipients": {
      "href": "https://actionnetwork.org/api/v2/lists/950e9954-606f-43e6-be99-2bc0bc2072a1"
    },
    "osdi:send_helper": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d/send"
    },
    "osdi:schedule_helper": {
      "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d/schedule"
    }
  }
}

The statistics field contains all of the engagement statistics for this email. Poll this endpoint to see updated statistics.

Click here for full documentation of message resources.

Back To Top ↑