Messages Version 2

This document describes the OSDI messages collection and message resource as implemented by the Action Network.

Messages are mass emails created by the organizer or group associated with your API key that are sent to activists subscribed to the group or organizer's email list or portions of the list, based on the email's targeting.

Messages have names (corresponding to our administrative titles), subject lines, from lines, and body contents, and they can have arrays of targets representing queries that are used to target this email, statistics about how the email is doing, and other fields. They are linked to a wrapper representing the email wrapper being used with the message and a list representing the people who received the message.

Messages are not deduplicated except on identifiers, to keep identifiers unique. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique.

Unlike other resources on the API, the messages API replicates most of the functionality of our user interface, so it is possible to create, target, schedule or send (using the schedule and send helpers), and report on email statistics all via the API.

Sections:

Endpoints and URL structures

Endpoints:

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

Message resources live exclusively at the above endpoint. The endpoint returns a collection of all the messages associated with your API key.

URL Structures:

https://actionnetwork.org/api/v2/messages/[id]

To address a specific message, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/messages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

Back To Top ↑

Field names and descriptions

Petition fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. See the general concepts document for more information about identifiers.
origin_system string A human readable string identifying where this message originated. May be used in the user interface for this purpose.
created_date datetime The date and time the resource was created. System generated, not editable.
modified_date datetime The date and time the resource was last modified. System generated, not editable.
name string The message's administrative title, only shown internally and not publicly.
subject string Yes The message's subject line.
from string Yes The message's from line.
body string Yes The message's body content. May contain HTML.
reply-to string Yes The message's reply-to email address. Must be an email address.
administrative_url string The URL to this message's manage page on the Action Network. Not editable.
type enum The type of message. Always "email", and not editable.
status enum The current status of the email. One of "draft", "calculating" (if the email's targeting is currently being calculated), "sent", or "scheduled". Not editable.
total_targeted integer A read-only field indicating the total number of people currently targeted by this message.
sent_start_date datetime A read-only field indicating when the message was sent, in UTC.
scheduled_start_date datetime A read-only field indicating when the message is scheduled to be sent, in UTC.
targets Targets[] An array of URLs to query resources on the API used as includes for this message. Queries that are excluded are not shown. Other targeting options selected in the user interface are not shown. Click here for queries documentation.
statistics Statistics A hash of the engagement statistics for the message, if it has been sent.
Target fields:
Field Name Type Required on POST Description
name href The link to the query resource's API endpoint being included on the message. Queries that are excluded are not shown. Other targeting options selected in the user interface are not shown. Click here for queries documentation.
statistics fields:
Field Name Type Required on POST Description
sent integer The number of people this message was sent to. Not editable.
opened integer The number of people who opened this message. Not editable.
clicked integer The number of people who clicked a link this message. Not editable.
actions integer The number of people who took an action such as signed a petition because they received this message. Not editable. Only counts actions that are Action Network pages or widgets.
unsubscribed integer The number of people who unsubscribed from your list after receiving this message. Not editable.
bounced integer The number of people who bounced and were unsubscribed from your list after receiving this message. Not editable.
spam_reports integer The number of people who marked this message as spam and were unsubscribed from your list. Not editable.
Back To Top ↑

Links

Link Name Description
self A link to this individual message resource.
osdi:wrapper A link to the wrapper this message is using. Can be POSTed to attach a specific wrapper to the message you are creating. Only present if the wrapper is not our built-in wrapper. Click here for wrappers documentation.
osdi:recipients A link to the list of people this message was sent to. Only present if the message was sent. Click here for lists documentation.
osdi:send_helper A link to the send helper for this message. Click here for the send helper documentation.
osdi:schedule_helper A link to the schedule helper for this message. Click here for the send helper documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of message resources (GET)

Message resources are sometimes presented as collections of messages. For example, calling the messages endpoint will return a collection of all the messages associated with your API key.

Request

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

Header:
OSDI-API-Token: your_api_key_here
					

Response

						
200 OK

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


{
  "total_pages": 7,
  "per_page": 25,
  "page": 1,
  "total_records": 162,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/messages?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/messages"
    },
    "osdi:messages": [
      {
        "href": "https://actionnetwork.org/api/v2/messages/a4dde5b6-0512-48ea-b4ad-63a71117b43d"
      },
      {
        "href": "https://actionnetwork.org/api/v2/messages/a27178b9-45c3-4844-8ebf-ebd5da74a1e3"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:messages": [
      {
        "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,
          "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"
          }
        }
      },
      {
        "identifiers": [
          "action_network:a27178b9-45c3-4844-8ebf-ebd5da74a1e3",
          "foreign_system:1"
        ],
        "origin_system": "My Email Making System",
        "created_date": "2014-03-27T18:03:45Z",
        "modified_date": "2014-03-28T15:00:22Z",
        "subject": "FWD: Stop doing the bad thing",
        "body": "<p>Have you signed yet? The mayor should stop doing the bad thing.</p>",
        "from": "Progressive Action Now",
        "reply_to": "jane@progressiveactionnow.org",
        "administrative_url": "https://actionnetwork.org/emails/fwd-stop-doing-the-bad-thing/manage",
        "total_targeted": 12673,
        "status": "draft",
        "type": "email",
        "targets": [],
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/messages/a27178b9-45c3-4844-8ebf-ebd5da74a1e3"
          },
          "osdi:send_helper": {
            "href": "https://actionnetwork.org/api/v2/messages/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/send"
          },
          "osdi:schedule_helper": {
            "href": "https://actionnetwork.org/api/v2/messages/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/schedule"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
					
Back To Top ↑

Scenario: Retrieving an individual message resource (GET)

Calling an individual message resource will return the resource directly, along with all associated fields and appropriate links to additional information about the message.

Request

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

Header:
OSDI-API-Token: your_api_key_here
					

Response

						
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,
    "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"
    }
  }
}
					
Back To Top ↑

Scenario: Creating a new message (POST)

You can post a new message to the messages endpoint and a message resource will be created in our system.

Unlike other resources on the API, messages POSTed via the API will show up as emails in the Action Network user interface, and can be edited and interacted with in the interface just like any other email.

If you include links to valid query resources in the targets array, those queries will be added as includes for your message's targeting. Otherwise, the message's targeting will be blank, targeting the full list. You can edit the message in the user interface to change the targeting, add other targeting options not available on the API, or add a random limit at any time before the message is sent.

If you include a link to a valid wrapper in the links section of your POST, that wrapper will be used for that message. Otherwise, the default wrapper for the organizer or group associated with your API key will be used.

POSTing messages will immediately cause their targeting to run against the queries in the targets array you've provided, or against the full list if the array is empty. This puts the message in the "calculating" status while targeting calculates. The email cannot be sent until targeting has finished and the status is "draft" again, with a total_targeted greater than 0. You should poll the message's endpoint with GET regularly to see when the message moves from "calculating" to "draft," indicating targeting has finished and a new total_targeted count is available.

Note: Because POSTing a message causes targeting -- a computationally expensive calculation -- to kick off immediately, POST requests are heavily rate limited. You can only POST once every 30 seconds. If you attempt to POST more often you will receive a rate limit error. Your application should handle this error and either retry later or inform the user to try again later.

Request

						
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"
    }
  }
}
					

Response

						
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"
    }
  }
}
					

In the above example, you can see how the foreign identifier being posted is merged into the identifiers array. We will intelligently search and deduplicate based on foreign and native identifiers. So if you post a message with an identifier that matches one already assigned to a message resource, your POST request will update that resource with new information instead of creating a duplicate. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique.

You can see that the message also 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.

And of course you can post a message with more fields (such as a name) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying a message (PUT)

You can modify an existing message by using PUT on its individual endpoint.

Request

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

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

{	
  "name": "Stop doing the bad thing email send 1",
  "subject": "Please! Stop doing the bad thing"
}
					

Response

						
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",
  "name": "Stop doing the bad thing email send 1",
  "subject": "Please! 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": "draft",
  "total_targeted": 2354,
  "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"
    }
  }
}
					

The above example added a name (an administrative title) to the message and changed the subject line.

Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the total_targeted count -- that is a system generated number reflecting a count of the total number of people targeted by the email. Invalid entries will be ignored.

PUTing changes to the targets array will immediately cause the email's targeting to run against the queries in the targets array you've provided, plus any other targeting parameters that have been added on the user interface. (This means you can edit targeting parameters on the UI as much as you'd like. The API will display queries in the includes column of the UI in the targets array on the API, but other parameters will be hidden and are inaccessible over the API, and thus cannot be changed via PUT.) This puts the message in the "calculating" status while targeting calculates. The email cannot be sent until targeting has finished and the status is "draft" again, with a total_targeted greater than 0. You should poll the message's endpoint with GET regularly to see when the message moves from "calculating" to "draft," indicating targeting has finished and a new total_targeted count is available.

If you PUT to change the targets array, the array will be replaced entirely by the contents of the new array you PUT. You can remove all queries from the targets array by PUTing a blank array item:

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

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

{	
  "targets": [
    ""
  ]
}
					

Note: Because PUTing a message that changes the targets array causes targeting -- a computationally expensive calculation -- to kick off immediately, PUT requests that change the targets array are heavily rate limited. You can only PUT to change the targets array once every 30 seconds. If you attempt to PUT more often after changing the targets array, you will receive a rate limit error. Your application should handle this error and either retry later or inform the user to try again later.

Back To Top ↑

Scenario: Deleting a message (DELETE)

Deleting messages is not allowed via the API. DELETE requests will return an error.

Back To Top ↑