/messages/email

Use this resource to list and create email messages.

Secured By: Authentication Token
Description:

List email messages.

Responses with more than 50 records will be paginated to 50 records per response, unless otherwise specified.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Query Parameters

Name Required Type Description
page_size integer

Limit number of messages returned with each request.

Minimum Value: 1

Maximum Value: 100

Example

messages/email?page_size=5
sort_by string

Field by which to sort results.

Default Value: created_at

Example

messages/email?sort_by=created_at
sort_order string

Order by which to sort results.

Default Value: DESC

Valid Values:

  • ASC
  • DESC

Example

messages/email?sort_order=ASC

Status

Headers

Name Type Description
Link string

Appropriate pagination link relations. Can include "first", "last", "prev", and "next" relations.

Example

< /messages/email?page=1>; rel="first",
< /messages/email?page=2>; rel="prev",
< /messages/email?page=4>; rel="next",
< /messages/email?page=5>; rel="last"

Body

Format: application/json

Example
[
  {
    "id": 10021,
    "subject": "This is the subject",
    "created_at": "2013-01-30T17:45:27Z",
    "status": "completed",
    "_links": {
      "self": "/messages/email/10021",
      "recipients": "/messages/email/10021/recipients",
      "failed": "/messages/email/10021/recipients/failed",
      "sent": "/messages/email/10021/recipients/sent",
      "clicked": "/messages/email/10021/recipients/clicked",
      "opened": "/messages/email/10021/recipients/opened"
    }
  },
  {
    "id": 10040,
    "subject": "Today's Weather",
    "created_at": "2014-05-30T12:54:46Z",
    "status": "completed",
    "_links": {
      "self": "/messages/email/10040",
      "email_template": "new_template-1",
      "recipients": "/messages/email/10040/recipients",
      "failed": "/messages/email/10040/recipients/failed",
      "sent": "/messages/email/10040/recipients/sent",
      "clicked": "/messages/email/10040/recipients/clicked",
      "opened": "/messages/email/10040/recipients/opened"
    }
  }
]
Schema
Array of objects that may include:
Name Type Description
subject string

Subject line of the email

Example

Today's Weather
created_at string

The date and time when the message was created.

Example

2013-01-30T17:45:27Z
_links object

An object that defines links to related objects.

Properties

{
  "self": {
    "description": "Relative URI of the object",
    "type": "string",
    "example": "/messages/email/10040"
  },
  "email_template": {
    "description": "UID of the template used while sending the email.",
    "type": "string",
    "example": "new_template-1"
  },
  "recipients": {
    "description": "Relative URI to the list of recipients of the message",
    "type": "string",
    "example": "/messages/email/10040/recipients"
  },
  "failed": {
    "description": "Relative URI to the list of emails with a failed link",
    "type": "string",
    "example": "/messages/email/10040/recipients/failed"
  },
  "sent": {
    "description": "Relative URI to the list of emails with a sent link",
    "type": "string",
    "example": "/messages/email/10040/recipients/sent"
  },
  "clicked": {
    "description": "Relative URI to the list of emails with a clicked link",
    "type": "string",
    "example": "/messages/email/10040/recipients/clicked"
  },
  "opened": {
    "description": "Relative URI to the list of emails that have been opened",
    "type": "string",
    "example": "/messages/email/10040/recipients/opened"
  }
}
status string

new - message has been created

queued - message has been queued for sending

sending - message has begun sending

completed - all recipients have positive confirmation or have expired

Valid Values:

  • new
  • queued
  • sending
  • completed

Example

completed
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Email Messages",
  "description": "A List of email messageses you have sent.",
  "type": "array",
  "items": {
    "title": "Email Message",
    "type": "object",
    "properties": {
      "subject": {
        "description": "Subject line of the email",
        "type": "string",
        "example": "Today's Weather"
      },
      "created_at": {
        "description": "The date and time when the message was created.",
        "type": "string",
        "example": "2013-01-30T17:45:27Z"
      },
      "_links": {
        "title": "Relational Links",
        "description": "An object that defines links to related objects.",
        "type": "object",
        "properties": {
          "self": {
            "description": "Relative URI of the object",
            "type": "string",
            "example": "/messages/email/10040"
          },
          "email_template": {
            "description": "UID of the template used while sending the email.",
            "type": "string",
            "example": "new_template-1"
          },
          "recipients": {
            "description": "Relative URI to the list of recipients of the message",
            "type": "string",
            "example": "/messages/email/10040/recipients"
          },
          "failed": {
            "description": "Relative URI to the list of emails with a failed link",
            "type": "string",
            "example": "/messages/email/10040/recipients/failed"
          },
          "sent": {
            "description": "Relative URI to the list of emails with a sent link",
            "type": "string",
            "example": "/messages/email/10040/recipients/sent"
          },
          "clicked": {
            "description": "Relative URI to the list of emails with a clicked link",
            "type": "string",
            "example": "/messages/email/10040/recipients/clicked"
          },
          "opened": {
            "description": "Relative URI to the list of emails that have been opened",
            "type": "string",
            "example": "/messages/email/10040/recipients/opened"
          }
        }
      },
      "status": {
        "description": "new - message has been created\n\nqueued - message has been queued for sending\n\nsending - message has begun sending\n\ncompleted - all recipients have positive confirmation or have expired",
        "type": "string",
        "enum": [
          "new",
          "queued",
          "sending",
          "completed"
        ],
        "example": "completed"
      }
    }
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}
Secured By: Authentication Token
Description:

Creates a new Email message.

Headers

Name Required Type Description
X-AUTH-TOKEN * string

An authentication token provided to you by GovDelivery.

Body

Format: application/json

Example
{
  "subject": "Today's Weather",
  "body": "Today it is Sunny and 70F at [[address]] [[city]]. Weather brought to you by [[company]] - [[url]]",
  "recipients": [
    {
      "email": "test01@test.govdelivery.com",
      "macros": {
        "city": "RECIPIENT Saint Paul",
        "address": "RECIPIENT 408 Saint Peter Street",
        "company": "RECIPIENT GovDelivery",
        "url": "RECIPIENT www.govdelivery.com"
      }
    },
    {
      "email": "test02@test.govdelivery.com",
      "macros": {
        "city": "RECIPIENT Minneapolis",
        "address": "RECIPIENT 1234 Main Street",
        "company": "RECIPIENT Company Name",
        "url": "RECIPIENT www.example.com"
      }
    }
  ],
  "from_name": "Weather Bot",
  "from_email": "weather@example.com",
  "open_tracking_enabled": true,
  "click_tracking_enabled": true,
  "message_type_code": "salutations",
  "macros": {
    "city": "DEFAULT Saint Paul",
    "address": "DEFAULT 408 Saint Peter Street",
    "company": "DEFAULT GovDelivery",
    "url": "DEFAULT www.govdelivery.com"
  },
  "_links": {
    "email_template": "new_template-10"
  }
}
Schema
Object that may include:
Name Required Type Description
subject string

Subject line of the email. Required if a template is not specified. If a template is specified and subject is provided, then the provided subject will be used instead of the template's subject.

Example

Today's Weather
body string

Body of the email. Required if a template is not specified. If a template is specified and body is provided, then the provided body will be used instead of the template's body.

Example

Today is Sunny and 70F.
recipients * string

List of objects defining who will receive the email. Objects must include an "email" attribute. Objects may include a "macros" attribute whose value is an object mapping macro names to values to be used.

Example

[
    {
      "email": "test01@test.govdelivery.com",
      "macros": {
        "city": "RECIPIENT Saint Paul",
        "address": "RECIPIENT 408 Saint Peter Street",
        "company": "RECIPIENT GovDelivery",
        "url": "RECIPIENT www.govdelivery.com"
      }
    },
    {
      "email": "test02@test.govdelivery.com",
      "macros": {
        "city": "RECIPIENT Minneapolis",
        "address": "RECIPIENT 1234 Main Street",
        "company": "RECIPIENT Company Name",
        "url": "RECIPIENT www.example.com"
      }
    }
]
from_name string

Display name of the sender. If a template is specified and a from_name is provided, then the provided from_name will be used instead of the template's from_name.

Example

Weather Bot
from_email string

Email address of the sender. Must be an email address authorized to send from your account.

Example

weather@example.com
click_tracking_enabled boolean

Enable or disable click tracking for an email message. If a template is provided, than the default value will be the value of that template's click_tracking_enabled attribute. Otherwise, defaults to true.

open_tracking_enabled boolean

Enable or disable open tracking for an email message. If a template is provided, then the default value will be the value of that template's open_tracking_enabled attribute. Otherwise, defaults to true.

message_type_code string

The unique identifier of the Message Type to associate with this message. A Message Type will be created if it doesn't exist. The Message Type's label will be generated from this value, and can be updated via the Message Type resource.

macros string

List of macros valid for the message, including the default values that will be used if the macros are missing for any recipients. If a template is provided, any macros and default values provided here will be merged with any macros defined in the specifided template, with the default values provided here overriding the default values defined by the template.

Example

{
    "city": "DEFAULT Saint Paul",
    "address": "DEFAULT 408 Saint Peter Street",
    "company": "DEFAULT GovDelivery",
    "url": "DEFAULT www.govdelivery.com"
}
_links string

The links to be associated with this email message.

Possible Parameters are:

  • email_template:
    • Required: No
    • UUID of a template to use. For more information on templates, see documentation for the /templates/email endpoint.

Example

{
  "email_template": "new_template-1"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "/messages/email",
  "description": "Creates a new Email message.",
  "type": "object",
  "properties": {
    "subject": {
      "description": "Subject line of the email. Required if a template is not\nspecified. If a template is specified and subject is provided,\nthen the provided subject will be used instead of the\ntemplate's subject.\n",
      "type": "string",
      "example": "Today's Weather"
    },
    "body": {
      "description": "Body of the email. Required if a template is not specified. If\na template is specified and body is provided, then the provided\nbody will be used instead of the template's body.\n",
      "type": "string",
      "example": "Today is Sunny and 70F."
    },
    "recipients": {
      "description": "List of objects defining who will receive the email. Objects\nmust include an \"email\" attribute. Objects may include a\n\"macros\" attribute whose value is an object mapping macro names\nto values to be used.\n",
      "type": "string",
      "example": "[\n    {\n      \"email\": \"test01@test.govdelivery.com\",\n      \"macros\": {\n        \"city\": \"RECIPIENT Saint Paul\",\n        \"address\": \"RECIPIENT 408 Saint Peter Street\",\n        \"company\": \"RECIPIENT GovDelivery\",\n        \"url\": \"RECIPIENT www.govdelivery.com\"\n      }\n    },\n    {\n      \"email\": \"test02@test.govdelivery.com\",\n      \"macros\": {\n        \"city\": \"RECIPIENT Minneapolis\",\n        \"address\": \"RECIPIENT 1234 Main Street\",\n        \"company\": \"RECIPIENT Company Name\",\n        \"url\": \"RECIPIENT www.example.com\"\n      }\n    }\n]\n"
    },
    "from_name": {
      "description": "Display name of the sender. If a template is specified and a\nfrom_name is provided, then the provided from_name will be used\ninstead of the template's from_name.\n",
      "type": "string",
      "example": "Weather Bot"
    },
    "from_email": {
      "description": "Email address of the sender. Must be an email address authorized\nto send from your account.\n",
      "type": "string",
      "example": "weather@example.com"
    },
    "click_tracking_enabled": {
      "description": "Enable or disable click tracking for an email message. If a\ntemplate is provided, than the default value will be the\nvalue of that template's click_tracking_enabled attribute.\nOtherwise, defaults to true.\n",
      "type": "boolean"
    },
    "open_tracking_enabled": {
      "description": "Enable or disable open tracking for an email message. If a\ntemplate is provided, then the default value will be the\nvalue of that template's open_tracking_enabled attribute.\nOtherwise, defaults to true.\n",
      "type": "boolean"
    },
    "message_type_code": {
      "description": "The unique identifier of the Message Type to associate\nwith this message. A Message Type will be created if it doesn't\nexist. The Message Type's label will be generated from this value,\nand can be updated via the Message Type resource.\n",
      "type": "string"
    },
    "macros": {
      "description": "List of macros valid for the message, including the default\nvalues that will be used if the macros are missing for any\nrecipients. If a template is provided, any macros and\ndefault values provided here will be merged with any macros\ndefined in the specifided template, with the default values\nprovided here overriding the default values defined by the\ntemplate.\n",
      "type": "string",
      "example": "{\n    \"city\": \"DEFAULT Saint Paul\",\n    \"address\": \"DEFAULT 408 Saint Peter Street\",\n    \"company\": \"DEFAULT GovDelivery\",\n    \"url\": \"DEFAULT www.govdelivery.com\"\n}\n"
    },
    "_links": {
      "description": "The links to be associated with this email message.\n\nPossible Parameters are:\n\n  - email_template:\n    - Required: No\n    - UUID of a template to use. For more information on\n      templates, see documentation for the\n      [/templates/email](/api/tms/resource/templates/email/)\n      endpoint.\n",
      "type": "string",
      "example": "{\n  \"email_template\": \"new_template-1\"\n}\n"
    }
  },
  "required": [
    "recipients"
  ]
}
Form Parameters
Name Required Type Description
subject string

Subject line of the email. Required if a template is not specified. If a template is specified and subject is provided, then the provided subject will be used instead of the template's subject.

Example

Today's Weather
body string

Body of the email. Required if a template is not specified. If a template is specified and body is provided, then the provided body will be used instead of the template's body.

Example

Today is Sunny and 70F.
recipients * string

List of objects defining who will receive the email. Objects must include an "email" attribute. Objects may include a "macros" attribute whose value is an object mapping macro names to values to be used.

Example

[
    {
      "email": "test01@test.govdelivery.com",
      "macros": {
        "city": "RECIPIENT Saint Paul",
        "address": "RECIPIENT 408 Saint Peter Street",
        "company": "RECIPIENT GovDelivery",
        "url": "RECIPIENT www.govdelivery.com"
      }
    },
    {
      "email": "test02@test.govdelivery.com",
      "macros": {
        "city": "RECIPIENT Minneapolis",
        "address": "RECIPIENT 1234 Main Street",
        "company": "RECIPIENT Company Name",
        "url": "RECIPIENT www.example.com"
      }
    }
]
from_name string

Display name of the sender. If a template is specified and a from_name is provided, then the provided from_name will be used instead of the template's from_name.

Example

Weather Bot
from_email string

Email address of the sender. Must be an email address authorized to send from your account.

Example

weather@example.com
click_tracking_enabled boolean

Enable or disable click tracking for an email message. If a template is provided, than the default value will be the value of that template's click_tracking_enabled attribute. Otherwise, defaults to true.

open_tracking_enabled boolean

Enable or disable open tracking for an email message. If a template is provided, then the default value will be the value of that template's open_tracking_enabled attribute. Otherwise, defaults to true.

message_type_code string

The unique identifier of the Message Type to associate with this message. A Message Type will be created if it doesn't exist. The Message Type's label will be generated from this value, and can be updated via the Message Type resource.

macros string

List of macros valid for the message, including the default values that will be used if the macros are missing for any recipients. If a template is provided, any macros and default values provided here will be merged with any macros defined in the specifided template, with the default values provided here overriding the default values defined by the template.

Example

{
    "city": "DEFAULT Saint Paul",
    "address": "DEFAULT 408 Saint Peter Street",
    "company": "DEFAULT GovDelivery",
    "url": "DEFAULT www.govdelivery.com"
}
_links string

The links to be associated with this email message.

Possible Parameters are:

  • email_template:
    • Required: No
    • UUID of a template to use. For more information on templates, see documentation for the /templates/email endpoint.

Example

{
  "email_template": "new_template-1"
}

Status

Body

Format: application/json

Example
{
  "from_name": "Weather Bot",
  "subject": "Today's Weather",
  "macros": {
    "city": "DEFAULT Saint Paul",
    "address": "DEFAULT 408 Saint Peter Street",
    "company": "DEFAULT GovDelivery",
    "url": "DEFAULT www.govdelivery.com"
  },
  "body": "Today it is Sunny and 70F at [[address]] [[city]]. Weather brought to you by [[company]] - [[url]]",
  "from_email": "weather@example.com",
  "reply_to": "weather@example.com",
  "errors_to": "weather@example.com",
  "open_tracking_enabled": true,
  "click_tracking_enabled": true,
  "created_at": "2014-05-30T12:54:46Z",
  "message_type_code": "salutations",
  "completed_at": "2014-05-30T12:54:51Z",
  "status": "completed",
  "_links": {
    "self": "/messages/email/10040",
    "email_template": "27",
    "recipients": "/messages/email/10040/recipients",
    "clicked": "/messages/email/10040/recipients/clicked",
    "opened": "/messages/email/10040/recipients/opened"
  },
  "recipient_counts": {
    "total": 2,
    "new": 0,
    "sending": 0,
    "sent": 2,
    "failed": 0,
    "blacklisted": 0,
    "canceled": 0
  }
}
Schema
Object that may include:
Name Type Description
from_name string

Display name of the sender

Example

Weather Bot
from_email string

Email address of the sender. Must be an email address authorized to send from your account.

Example

weather@example.com
reply_to string

Address to set reply-to email header to

Example

replies@example.com
errors_to string

Address to set the errors-to email header to

Example

errors@example.com
subject string

Subject line of the email

Example

Today's Weather
macros object

List of valid for the message, including their default values that will be used if the macros are missing for any recipients

Example

{
  "city": "DEFAULT Saint Paul",
  "address": "DEFAULT 408 Saint Peter Street",
  "company": "DEFAULT GovDelivery",
  "url": "DEFAULT www.govdelivery.com"
}
body string

Body of the email

Example

Today is Sunny and 70F.
click_tracking_enabled boolean

Enable or disable click tracking for an email message, defaults to true

Default Value: true

open_tracking_enabled boolean

Enable or disable open tracking for an email message, defaults to true

Default Value: true

message_type_code string

The code of the message_type

Example

salutations
created_at string

The date and time when the message was created.

Example

2013-01-30T17:45:27Z
_links object

An object that defines links to related objects.

Properties

{
  "self": {
    "description": "Relative URI of the object",
    "type": "string",
    "example": "/messages/email/10040"
  },
  "email_template": {
    "description": "UID of the email template used while sending the email",
    "type": "string",
    "example": "new_template-1"
  },
  "recipients": {
    "description": "Relative URI to the list of recipients of the message",
    "type": "string",
    "example": "/messages/email/10040/recipients"
  },
  "clicked": {
    "description": "Relative URI to the list of emails with a clicked link",
    "type": "string",
    "example": "/messages/email/10040/recipients/clicked"
  },
  "opened": {
    "description": "Relative URI to the list of emails that have been opened",
    "type": "string",
    "example": "/messages/email/10040/recipients/opened"
  }
}
status string

new - message has been created

queued - message has been queued for sending

sending - message has begun sending

completed - all recipients have positive confirmation or have expired

Valid Values:

  • new
  • queued
  • sending
  • completed

Example

completed
recipient_counts object

Rollup of the recipient states to give you at-a-glance metrics on the message.

Example

{
  "total": 2,
  "new": 0,
  "sending": 0,
  "sent": 2,
  "failed": 0,
  "blacklisted": 0,
  "canceled": 0
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Email Message",
  "description": "Details of a single email message.",
  "type": "object",
  "properties": {
    "from_name": {
      "description": "Display name of the sender",
      "type": "string",
      "example": "Weather Bot"
    },
    "from_email": {
      "description": "Email address of the sender. Must be an email address authorized\nto send from your account.\n",
      "type": "string",
      "example": "weather@example.com"
    },
    "reply_to": {
      "description": "Address to set reply-to email header to",
      "type": "string",
      "example": "replies@example.com"
    },
    "errors_to": {
      "description": "Address to set the errors-to email header to",
      "type": "string",
      "example": "errors@example.com"
    },
    "subject": {
      "description": "Subject line of the email",
      "type": "string",
      "example": "Today's Weather"
    },
    "macros": {
      "description": "List of  valid for the message, including their default values that will be used if the macros are missing for any recipients",
      "type": "object",
      "example": "{\n\"city\": \"DEFAULT Saint Paul\",\n\"address\": \"DEFAULT 408 Saint Peter Street\",\n\"company\": \"DEFAULT GovDelivery\",\n\"url\": \"DEFAULT www.govdelivery.com\"\n}"
    },
    "body": {
      "description": "Body of the email",
      "type": "string",
      "example": "Today is Sunny and 70F."
    },
    "click_tracking_enabled": {
      "description": "Enable or disable click tracking for an email message, defaults to true",
      "type": "boolean",
      "default": true
    },
    "open_tracking_enabled": {
      "description": "Enable or disable open tracking for an email message, defaults to true",
      "type": "boolean",
      "default": true
    },
    "message_type_code": {
      "description": "The code of the message_type",
      "type": "string",
      "example": "salutations"
    },
    "created_at": {
      "description": "The date and time when the message was created.",
      "type": "string",
      "example": "2013-01-30T17:45:27Z"
    },
    "_links": {
      "title": "Relational Links",
      "description": "An object that defines links to related objects.",
      "type": "object",
      "properties": {
        "self": {
          "description": "Relative URI of the object",
          "type": "string",
          "example": "/messages/email/10040"
        },
        "email_template": {
          "description": "UID of the email template used while sending the email",
          "type": "string",
          "example": "new_template-1"
        },
        "recipients": {
          "description": "Relative URI to the list of recipients of the message",
          "type": "string",
          "example": "/messages/email/10040/recipients"
        },
        "clicked": {
          "description": "Relative URI to the list of emails with a clicked link",
          "type": "string",
          "example": "/messages/email/10040/recipients/clicked"
        },
        "opened": {
          "description": "Relative URI to the list of emails that have been opened",
          "type": "string",
          "example": "/messages/email/10040/recipients/opened"
        }
      }
    },
    "status": {
      "description": "new - message has been created\n\nqueued - message has been queued for sending\n\nsending - message has begun sending\n\ncompleted - all recipients have positive confirmation or have expired",
      "type": "string",
      "enum": [
        "new",
        "queued",
        "sending",
        "completed"
      ],
      "example": "completed"
    },
    "recipient_counts": {
      "description": "Rollup of the recipient states to give you at-a-glance metrics on the message.",
      "type": "object",
      "example": "{\n\"total\": 2,\n\"new\": 0,\n\"sending\": 0,\n\"sent\": 2,\n\"failed\": 0,\n\"blacklisted\":0,\n\"canceled\":0\n}"
    }
  }
}
Description

Unprocessable Entity

Body

Format: application/json

Example
{
  "from_name": "From Name",
  "subject": null,
  "macros": {
  },
  "body": null,
  "open_tracking_enabled": true,
  "click_tracking_enabled": true,
  "created_at": null,
  "status": "new",
  "_links": {
    "self": "/messages/email",
    "recipients": null,
    "clicked": null,
    "opened": null
  },
  "errors": {
    "body": [
      "can't be blank"
    ],
    "subject": [
      "can't be blank"
    ]
  }
}

Body

Format: application/json

Example
{
  "error": "Invalid authentication token"
}