List Email Object

A list email is a single email sent to a recipient list.

Learn more about list emails in Salesforce Help.

The API to access the List Email object follows the conventions described in Version 5 Overview.

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Create	`POST`	`https://pi.pardot.com/api/v5/objects/list-emails?<params>`	Marketing > Emails > Emails > Send To List ability
Read	`GET`	`https://pi.pardot.com/api/v5/objects/list-emails/<id>?<params>`	Marketing > Emails > Emails > View ability
Query	`GET`	`https://pi.pardot.com/api/v5/objects/list-emails?<params>`	Marketing > Emails > Emails > View ability
Statistics	`GET`	`https://pi.pardot.com/api/v5/objects/list-emails/<id>/stats`	Marketing > Emails > Emails > View Report ability

Fields

Required Editable Fields

Field	Type	Description
`name`	String	The name of the object for identification in Account Engagement.
`campaignId`	Integer	The ID of the campaign related to this object.
`recipientListIds`	Array	An array of IDs of the recipient lists. The email is sent to all users on the specified lists. Write-Only field on create operation.

Optional Editable Fields

Field	Type	Description
`subject`	String	The list email subject.
`textMessage`	String	The text content of the email’s message. This field isn’t queryable.
`htmlMessage`	String	The HTML content of the email’s message. This field isn’t queryable.
`senderOptions`	Sender Options[]	An array of the sender options.
`replyToOptions`	Reply To Options[]	An array of the reply to address options.
`scheduledTime`	DateTime	The ISO 8601 date and time to send the email. Write-Only field on create operation.
`isOperational`	Boolean	When `true`, the email is sent to the prospect regardless of opt-out status. Your account must have Operational Email Sending enabled to use this setting.
`emailTemplateId`	Integer	The ID of the email template used for the list email.
`trackerDomainId`	Integer	The ID of the tracker domain used for the list email.
`suppressionListIds`	Array	An array of IDs of the suppression lists. The email isn’t sent to any user on the suppression lists. Write-Only field on create operation.
`folderId`	Integer	The ID of the folder containing this object.

Read-Only Fields

Field	Type	Description
`id`	Integer	The ID of the list email.
`isPaused`	Boolean	True if the email send is paused.
`isSent`	Boolean	True if the email has been sent.
`isDeleted`	Boolean	True if the object is in the recycle bin in Account Engagement.
`clientType`	String	The type of client that was used to send the email. The value is `Builder` if the email was sent using the Lightning Email Builder, or `Web` if it was sent using the legacy Pardot email builder.
`createdById`	Integer	The ID of the user who created this object.
`updatedById`	Integer	The ID of the user who last updated this object.
`createdAt`	DateTime	Creation time of the list email.
`updatedAt`	DateTime	Last update time of the list email.
`sentAt`	DateTime	The date and time when the list email was sent.
`operationalEmail`	Boolean	Deprecated. Use isOperational instead. True if the email is operational.
`recipientLists`	Recipient Lists[]	An array of the lists used for this list email.
`suppressionLists`	Suppression Lists[]	An array of the lists used as suppression lists for the list email.
`createdBy`	User	User object representing the user who created this object. See documentation for User for fields.
`updatedBy`	User	User object representing the user who last updated this object. See documentation for User for fields.
`campaign`	Campaign	Campaign object representing the campaign that was set on Create. See documentation for Campaign for fields.
`folder`	Folder	JSON object representing the folder for this object. See documentation for Folder for fields.
`trackerDomain`	Tracker Domain	Tracker Domain object representing the tracker domain associated with this object. See documentation for Tracker Domain for fields.
`type`	Enum	The content type of the email. Possible values are `html` (Read and Query only), `text`, and `htmlAndText`.

senderOptions Fields

Field Name	Data Type	Description
`senderOptions.type`	Enum`<string>`	The sending user type. Can be `general_user`, `specific_user`, `assigned_user` or `account_owner`. When performing read or query, `account_custom_field` and `prospect_custom_field` are also available.
`senderOptions.address`	String	The sending email address.
`senderOptions.name`	String	The name of the sender.
`senderOptions.userId`	Integer	The user ID of the sender.
`senderOptions.prospectCustomFieldId`	Integer	The ID of the prospect custom field that contains the sender value.
`senderOptions.accountCustomFieldId`	Integer	The ID of the account custom field that contains the sender value.

replyToOptions Fields

Field Name	Data Type	Description
`replyToOptions.type`	Enum`<string>`	The reply to user type. Can be `general_address`, `specific_user`, `assigned_user` or `account_owner`. When performing read or query, `account_custom_field` and `prospect_custom_field` are also available.
`replyToOptions.address`	String	The reply-to email address.
`replyToOptions.userId`	Integer	The user ID of the reply to sender.
`replyToOptions.prospectCustomFieldId`	Integer	The ID of the prospect custom field that contains the reply to value. This field isn’t editable.
`replyToOptions.accountCustomFieldId`	Integer	The ID of the account custom field that contains the reply to value. This field isn’t editable.

List Email Create

Send an email to every prospect on the specified list following the conventions described in the Version 5 Overview.

Example Request

1POST /api/v5/objects/list-emails?fields=id,name,subject,htmlMessage,textMessage,campaignId,sentAt,isOperational,trackerDomainId,emailTemplateId,folderId,type,isPaused,isSent,isDeleted,replyToOptions.type,senderOptions.type,clientType,createdById,updatedById,createdAt,updatedAt HTTP/1.1
2Host: pi.pardot.com
3Pardot-Business-Unit-Id: <business-unit-id>
4Authorization: Bearer <access-token>
5
6{
7    "name": "New List Email",
8    "subject": "Greetings",
9    "htmlMessage": "<html><head></head><body>hello, goodbye. %%unsubscribe%%</body></html>",
10    "textMessage": "hello, %%unsubscribe%%",
11    "campaignId" : 1001,
12    "folderId" : 500,
13    "trackerDomainId": 5,
14    "scheduledTime" : "2034-07-25T14:01:17-04:00",
15    "recipientListIds" : [5],
16    "suppressionListIds" : [6],
17    "isOperational": false,
18    "emailTemplateId": 22,
19    "senderOptions" : [
20        {
21            "type" : "account_owner"
22        },
23        {
24            "type" : "general_user",
25            "name" : "Marketing Team",
26            "address" : "test@example.com"
27        },
28        {
29            "type" : "specific_user",
30            "userId" : 10000
31        }
32    ],
33    "replyToOptions" : [
34        {
35            "type" : "specific_user",
36            "userId" : 10000
37        },
38        {
39            "type" : "general_address",
40            "address" : "test@test.com"
41        }
42    ]
43}

A successful request returns an HTTP 201 response. The response lists the fields that were specified in the request.

List Email Read

Retrieve a single list email following the conventions described in the Version 5 Overview.

Example request:

1GET /api/v5/objects/list-emails/1000?fields=id,name,subject,htmlMessage,textMessage,campaignId,isPaused,isSent,isDeleted,replyToOptions.type,replyToOptions.address,senderOptions.type,senderOptions.name,senderOptions.address,clientType,createdById,updatedById,createdAt,updatedAt,sentAt,isOperational,trackerDomainId,emailTemplateId,recipientLists.id,recipientLists.name,recipientLists.description,recipientLists.title,recipientLists.isDeleted,recipientLists.isDynamic,recipientLists.isPublic,recipientLists.isSalesforceVisible,recipientLists.createdById,recipientLists.updatedById,recipientLists.createdAt,recipientLists.updatedAt,recipientLists.folderId,recipientLists.campaignId,suppressionLists.id,suppressionLists.name,suppressionLists.description,suppressionLists.title,suppressionLists.isDeleted,suppressionLists.isDynamic,suppressionLists.isPublic,suppressionLists.isSalesforceVisible,suppressionLists.createdById,suppressionLists.updatedById,suppressionLists.createdAt,suppressionLists.updatedAt,suppressionLists.folderId,suppressionLists.campaignId HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <token>

Example response:

1{
2  "id": 1000,
3  "campaignId": 2000,
4  "clientType": "Web",
5  "createdAt": "2015-10-12T13:11:27+09:00",
6  "createdById": 1,
7  "emailTemplateId": null,
8  "htmlMessage": "<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"><head><meta http-equiv=\"Content-Type\" content=\"text/html;\" /><title>Email Newsletter</title></head><body style=\"font-family: Helvetica, Arial, sans-serif; font-size: 12px\">\nMy HTML Content</body></html>",
9  "isDeleted": false,
10  "isPaused": false,
11  "isSent": true,
12  "name": "Fall Signup",
13  "isOperational": false,
14  "recipientLists": [
15    {
16      "id": 3000,
17      "campaignId": null,
18      "createdAt": "2015-10-11T12:24:47+09:00",
19      "createdById": 1,
20      "description": null,
21      "folderId": 4820,
22      "isDeleted": false,
23      "isDynamic": false,
24      "isPublic": false,
25      "isSalesforceVisible": false,
26      "name": "Fall Training Candidates",
27      "title": null,
28      "updatedAt": "2015-10-11T12:25:04+09:00",
29      "updatedById": 1
30    }
31  ],
32  "replyToOptions": null,
33  "senderOptions": [
34    {
35      "address": "lenoxsoft@example.com",
36      "name": "LenoxSoft",
37      "type": "general_user"
38    }
39  ],
40  "sentAt": "2015-10-12T22:05:00+09:00",
41  "subject": "Fall Training",
42  "suppressionLists": null,
43  "textMessage": "My text content\n\n",
44  "trackerDomainId": null,
45  "updatedAt": "2015-10-12T22:58:57+09:00",
46  "updatedById": 1
47}

List Email Query

Retrieving a collection of list emails follows the conventions described in Version 5 Overview.

Example request:

1GET /api/v5/objects/list-emails?fields=id,name,subject,campaignId,isPaused,isSent,isDeleted,clientType,createdById,updatedById,createdAt,updatedAt,sentAt,isOperational,trackerDomainId,emailTemplateId,replyToOptions.address,senderOptions.address HTTP/1.1
2Authorization: Bearer <token>
3Host: pi.pardot.com

Example response:

1{
2  "nextPageToken": null,
3  "nextPageUrl": null,
4  "values": [
5    {
6      "id": 64610046,
7      "campaignId": 648,
8      "clientType": "Web",
9      "createdAt": "2015-08-29T03:58:33+09:00",
10      "createdById": 1,
11      "emailTemplateId": 11548,
12      "isDeleted": false,
13      "isPaused": false,
14      "isSent": true,
15      "name": "Test",
16      "isOperational": false,
17      "replyToOptions": null,
18      "senderOptions": [
19        {
20          "address": "marketer@example.com"
21        },
22        {
23          "address": null
24        }
25      ],
26      "sentAt": "2015-08-29T03:59:32+09:00",
27      "subject": "Subject",
28      "trackerDomainId": null,
29      "updatedAt": "2015-08-29T04:37:18+09:00",
30      "updatedById": 1
31    },
32    {
33      "id": 64610168,
34      "campaignId": 648,
35      "clientType": "Web",
36      "createdAt": "2015-08-29T04:08:39+09:00",
37      "createdById": 1,
38      "emailTemplateId": 11548,
39      "isDeleted": false,
40      "isPaused": false,
41      "isSent": true,
42      "name": "Test 2",
43      "isOperational": false,
44      "replyToOptions": null,
45      "senderOptions": [
46        {
47          "address": "admin@example.com"
48        },
49        {
50          "address": null
51        }
52      ],
53      "sentAt": "2015-08-29T04:09:34+09:00",
54      "subject": "Subject",
55      "trackerDomainId": null,
56      "updatedAt": "2015-08-29T04:37:18+09:00",
57      "updatedById": 1
58    }
59  ]
60}

List Email Statistics

Request statistical information for a list email, such as the number of clicks, opens, and opt-outs.

Example request:

1GET /api/v5/objects/list-emails/1000/stats HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <token>

Example response:

1{
2  "clickOpenRatio": 0,
3  "clickThroughRate": 1.9047,
4  "delivered": 21651,
5  "deliveryRate": 0.5225,
6  "hardBounced": 13692,
7  "listEmailId": 1000,
8  "opens": 0,
9  "opensRate": 0,
10  "optOutRate": 0.5318,
11  "optOuts": 11513,
12  "sent": 41434,
13  "softBounced": 7603,
14  "spamComplaintRate": 0,
15  "spamComplaints": 0,
16  "totalClicks": 41239,
17  "uniqueClickThroughRate": 0.7723,
18  "uniqueClicks": 16722,
19  "uniqueOpens": 0
20}

Sortable Fields

When executing a query, the following fields can be specified. See the conventions for query described in the Version 5 Overview.

id
createdAt
updatedAt
sentAt

Filtering Results

When executing a query, the following parameters can be used to filter the returned results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. When specifying more than one parameter, all parameters must match the record in order for it to be returned in the results.

Parameter	Description
`id`	Returns any list emails where ID is equal to the given integer value.
`idList`	Returns any list emails where ID is included in the given list of values.
`idGreaterThan`	Returns any list emails where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any list emails where ID is greater than or equal to the specified value.
`idLessThan`	Returns any list emails where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any list emails where ID is less than or equal to the specified value.
`createdAt`	Returns any list emails where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any list emails where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any list emails where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any list emails where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any list emails where CreatedAt is before or equal to the given datetime value.
`updatedAt`	Returns any list emails where UpdatedAt is equal to the given datetime value.
`updatedAtAfter`	Returns any list emails where UpdatedAt is after the given datetime value, non-inclusive.
`updatedAtAfterOrEqualTo`	Returns any list emails where UpdatedAt is after or equal to the given datetime value.
`updatedAtBefore`	Returns any list emails where UpdatedAt is before the given datetime value, non-inclusive.
`updatedAtBeforeOrEqualTo`	Returns any list emails where UpdatedAt is before or equal to the given datetime value.
`sentAt`	Returns any list emails where SentAt is equal to the given datetime value.
`sentAtAfter`	Returns any list emails where SentAt is after the given datetime value, non-inclusive.
`sentAtAfterOrEqualTo`	Returns any list emails where SentAt is after or equal to the given datetime value.
`sentAtBefore`	Returns any list emails where SentAt is before the given datetime value, non-inclusive.
`sentAtBeforeOrEqualTo`	Returns any list emails where SentAt is before or equal to the given datetime value.