Reading Emails

Supported Operations

For a complete list of fields involved in user operations, see the Email section of Object Field References.

Operation	URL Format	Required Parameters	Description
`read`	`/api/email/version/4/do/read/id/<email_id>?...`	`user_key, api_key, email_id`	Returns the data for the email specified by `<email_id>`. `<email_id>` is the Pardot ID of the target email.

Supported Parameters

Parameter	Required	Type	Description
include_message		boolean	When set to false, the email will not include the html nor text body message. Defaults to `true`.

XML Response Format

<rsp stat="ok" version="1.0">
    <email>
        ...
    </email>
</rsp>

Tag	Description
`<email>`	Parent tag. Contains data fields for target email. For complete field listing, see email in Object Field References.

Querying Email Stats

Supported Operations

For a complete list of fields involved in user operations, see the Email section of Object Field References.

Operation	URL Format	Required Parameters	Description
`stats`	`/api/email/version/4/do/stats/id/<list_email_id>?...`	`user_key, api_key, list_email_id`	Returns the statistical data for the list email specified by `<list_email_id>`. `<list_email_id>` is the Pardot ID of the target email.

XML Response Format

<rsp stat="ok" version="1.0">
    <stats>
        <sent>...</sent>
        <delivered>...</delivered>
        <total_clicks>...</total_clicks>
        <unique_clicks>...</unique_clicks>
        <soft_bounced>...</soft_bounced>
        <hard_bounced>...</hard_bounced>
        <opt_outs>...</opt_outs>
        <spam_complaints>...</spam_complaints>
        <opens>...</opens>
        <unique_opens>...</unique_opens>
        <delivery_rate>...</delivery_rate>
        <opens_rate>...</opens_rate>
        <click_through_rate>...</click_through_rate>
        <unique_click_through_rate>...</unique_click_through_rate>
        <click_open_ratio>...</click_open_ratio>
        <opt_out_rate>...</opt_out_rate>
        <spam_complaint_rate>...</spam_complaint_rate>
    </stats>
</rsp>

Tag	Description
`<stats>`	Contains the resulting email stats for the specified list email id.
`<sent>`	Contains the number of emails sent.
`<delivered>`	Contains the number of emails delivered.
`<total_clicks>`	Contains the number of total clicks for the email.
`<unique_clicks>`	Contains the number of unique clicks for the email.
`<soft_bounced>`	Contains the number of soft bounces for the email.
`<hard_bounced>`	Contains the number of hard bounces for the email.
`<opt_outs>`	Contains the number of opt outs for the email
`<spam_complaints>`	Contains the number of spam complaints for the email.
`<opens>`	Contains the number of opens for the email.
`<unique_opens>`	Contains the number of unique opens for the email.
`<delivery_rate>`	Contains the delivery rate based on the number of emails sent
`<opens_rate>`	Contains the open rate based on the number of emails delivered
`<click_through_rate>`	Contains the click through rate based on the number of emails delivered
`<unique_click_through_rate>`	Contains the unique click through rate based on the number of emails delivered
`<click_open_ratio>`	Contains the ratio between email clicks and opens
`<opt_out_rate>`	Contains the opt out rate based on the number of emails delivered
`<spam_complaint_rate>`	Contains the spam complaint rate based on the number of emails delivered

Sending One To One Emails

Supported Operations

For a complete list of fields involved in user operations, see the Email section of Object Field References.

Operation	URL Format	Required Parameters	Description
`send`	`/api/email/version/ 3/do/send/prospect_id/ <prospect_id>?...`	`user_key, api_key, campaign_id, (email_template_id OR (text_content, name, subject, & ((from_email & from_name) OR from_user_id)))`	Sends a one-to-one email to the prospect identified by `<prospect_id>`
`send`	`/api/email/version/ 3/do/send/prospect_email/ <prospect_email>?...`	`user_key, api_key, campaign_id, (email_template_id OR (text_content, name, subject, & ((from_email & from_name) OR from_user_id)))`	Sends a one-to-one email to the prospect identified by `<prospect_email>`

Supported Parameters

Parameter	Required	Type	Description
user_key	x	string	Your API user key. Required for all API requests.
api_key	x	string	Your api_key. Provided by authentication request. Required for all API requests.
campaign_id	x	integer	The id of the campaign you'd like this email associated with.
prospect_id	x****	integer	The id of the prospect you're sending the email to.
prospect_email	x****	string	The email of the prospect you're sending the email to.
from_name	x**	string	The name of the sending user.
from_email	x**	string	The email of the sending user.
from_user_id	x**	string	The user id of the sending user.
replyto_email		string	The email address where replies should be sent.
tags[]		string	The name of the tag you'd like to create or associate with this email. You can post multiple tags[] for multiple tags.
operational_email		boolean	When set, the email will be sent to the prospect regardless of opt-out status. Your account must have this feature enabled to use this setting.
name	x*	string	The name of the email within Pardot.
subject	x*	string	The subject of the email.
text_content	x*	string	The text body of the email. This must contain either %%unsubscribe%% or %%email_preference_center%%.
html_content		string	The html body of the email. This must contain either %%unsubscribe%% or %%email_preference_center%%.
email_template_id	x***	integer	The id of the email template to use.
format		(xml or json)	The format which the response will be sent. Xml is default.

* field is required if an email_template_id is not provided.

** (from_email & from_name) or from_user_id is required if an email_template_id is not provided.

*** if provided, the email template will be used first, then name, replyto_email, subject, text_content, and html_content will override the template contents if they're provided.

**** prospect_id or prospect_email is required.

Example Requests

This API request example made with cURL, will immediately send an email based on a template to a single prospect.

curl https://pi.pardot.com/api/email/version/4/do/send \
-H "Authorization: Pardot user_key={user_key},api_key={api_key}" \
--data-urlencode campaign_id=54321 \
--data-urlencode prospect_email=prospect@somecompany.com \
--data-urlencode email_template_id=6789 \
--data-urlencode format=json

XML Response Format

<rsp stat="ok" version="1.0">
    <email>
        ...
    </email>
</rsp>

Tag	Description
`<email>`	Parent tag. Contains data fields for target email. For complete field listing, see email in Object Field References.

Sending List Emails

Supported Operations

For a complete list of fields involved in user operations, see the Email section of Object Field References.

Operation	URL Format	Required Parameters	Description
`send`	`/api/email/version/4/do/send`	`user_key, api_key, list_ids[], campaign_id, (email_template_id OR (text_content, name, subject, & ((from_email & from_name) OR from_user_id)))`	Sends an email to all the prospects in a list identified by `list_ids[]`

Supported Parameters

Parameter	Required	Type	Description
user_key	x	string	Your API user key. Required for all API requests.
api_key	x	string	Your api_key. Provided by authentication request. Required for all API requests.
campaign_id	x	integer	The id of the campaign you'd like this email associated with.
from_name	x**	string	The name of the sending user.
from_email	x**	string	The email of the sending user.
from_user_id	x**	string	The user id of the sending user.
from_assigned_user		boolean	If the prospect has an assigned user, send the email from that user.
from_account_owner		boolean	If the prospect has an account owner, send the email from that user.
replyto_email		string	The email address where replies should be sent.
list_ids[]	x	integer	The id of the list you'd like to mail to. You can post multiple list_ids[] for multiple lists
suppression_list_ids[]		integer	The id of the list you'd like to suppress mailing to. You can post multiple suppression_list_ids[] for multiple lists.
tags[]		string	The name of the tag you'd like to create or associate with this email. You can post multiple tags[] for multiple tags.
operational_email		boolean	When set, the email will be sent to the prospect regardless of opt-out status. Your account must have this feature enabled to use this setting.
name	x*	string	The name of the email within Pardot.
subject	x*	string	The subject of the email.
text_content	x*	string	The text body of the email. This must contain either %%unsubscribe%% or %%email_preference_center%%.
html_content		string	The html body of the email. This must contain either %%unsubscribe%% or %%email_preference_center%%.
email_template_id	x***	integer	The id of the email template to use.
scheduled_time		ISO8601 string	The ISO8601 date and time which the email should be sent.
format		(xml or json)	The format which the response will be sent. Xml is default.

* field is required if an email_template_id is not provided.

** (from_email & from_name) or from_user_id is required if an email_template_id is not provided.

*** if provided, the email template will be used first, then name, from_assigned_user, replyto_email, subject, text_content, and html_content will override the template contents if they're provided.

Example Requests

This API request example made with cURL, will schedule an email based on a template to be sent on October 31st at 5pm GMT-4 to 4 prospect lists with 2 suppression lists. It will be sent from the assigned user, if one is assigned, and it also assigns 3 tags to the email.

curl https://pi.pardot.com/api/email/version/4/do/send \
-H "Authorization: Pardot user_key={user_key},api_key={api_key}" \
--data-urlencode campaign_id=54321 \
--data-urlencode from_assigned_user=1 \
--data-urlencode email_template_id=6789 \
--data-urlencode list_ids[]=123 \
--data-urlencode list_ids[]=456 \
--data-urlencode list_ids[]=789 \
--data-urlencode list_ids[]=101 \
--data-urlencode suppression_list_ids[]=987 \
--data-urlencode suppression_list_ids[]=654 \
--data-urlencode tags[]=new_prospect_email \
--data-urlencode tags[]=cart_abandoned \
--data-urlencode tags[]=subtotal_over_200 \
--data-urlencode scheduled_time=2013-10-31T17:00:00-0400 \
--data-urlencode format=json

XML Response Format

<rsp stat="ok" version="1.0">
    <email>
        ...
    </email>
</rsp>

Tag	Description
`<email>`	Parent tag. Contains data fields for target email. For complete field listing, see email in Object Field References.