# PyPardotSF
PyPardotSF is yet another fork of PyPardot/PyPardot4. The main driver for the
fork is to address Pardot's authentication change in Spring 2021 to use
Salesforce OAuth.
(As seen on [PyPardot4 Issue #46](https://github.com/mneedham91/PyPardot4/issues/46))
Another new features of PyPardotSF includes:
- Support both Versions 3 & 4 of Pardot API
- Support Version 3 & 4 [Import API (for Prospects)](https://developer.salesforce.com/docs/marketing/pardot/guide/import-v4.html)
This is a working prototype and the code is currently being cleaned up and
more detailed documentation is underway.
I'm keeping the original MIT License by the previous contributors.
Any contributions, including code, documentations, issue reporting are welcome.
## Install
```
pip install PyPardotSF
```
## Salesforce OAuth
### Get keys and tokens
Do this once when you do not have consumer key, secret, refresh token:
1. Open Python's interactive shell and run the following command:
```
$ python3
>>> from pypardot.client import PardotAPI
>>> p = PardotAPI(version=3) # verion=4 available
>>> p.setup_salesforce_auth_keys()
```
2. Follow the instruction in the command line to get the keys and
refresh token.
3. After you answer all the questions in the console, you should be able to
access API commands:
```
>>> p.prospects.read_by_email(email="daigo@anelen.co")
```
4. You can check the values of business unit id, consumer key, secret, and
refresh token:
```
>>> p.business_unit_id
'0Uv*****'
>>> p.sf_consumer_key
'xxxx'
>>> p.sf_consumer_secret
'yyyy'
>>> p.sftoken_refresh
'zzzz'
```
5. Please note them for the secondary and/or programmatic access.
(See the next section)
### Using the API client
```
from pypardot.client import PardotAPI
version = 3 # 3 or 4
sf_consumer_key = "xxxx"
sf_consumer_secret = "yyyy"
sf_refresh_token = "zzzz"
business_unit_id = "0Uv*****"
p = PardotAPI(
sf_consumer_key=sf_consumer_key,
sf_consumer_secret=sf_consumer_secret,
sf_refresh_token=sf_refresh_token,
business_unit_id=business_unit_id,
version=version)
p.prospects.read_by_email(email="daigo@anelen.co")
```
## Bulk Prospect Import
```
file_name = "data.csv"
columns = [
{
"field": "email"
},
{
"field": "pardot_field_a",
"overwrite": False,
"nullOverwrite": False
},
{
"field": "pardot_field_b",
"overwrite": False,
"nullOverwrite": False
},
}
results = client.importapi.create(
file_name=file_name,
operation="Upsert",
object="Prospect",
columns=columns,
restoreDeleted=config.get("restore_deleted", False),
)
batch_id = results["id"]
results = client.importapi.update(id=batch_id, state="Ready")
```
Check the import status at:
API Imports section at
[Admin->Import->Prospects](https://pi.pardot.com/import/wizardStep1)
## Other endpoints
Please see the original
[PyPardot](https://github.com/joshgeller/PyPardot) /
[PyPardot4](https://github.com/mneedham91/PyPardot4)
docs.
## Contributors wanted
My (Daigo Tanaka) access to Pardot may not be permanent and I curently have
access to Ver 3 API. So I would like this repository to be collaborative as
possible with the active Python programmers who uses Pardot API. This includes
the release process. I don't want to be a gate-keeper or a blocker.
Any bug fixes and enhancements are welcome and I trust your good intentions.
Together with the fellow contributors, I will help review the code from
good design and coding stand point, but I may not be able to run tests myself
for the reason I stated above. So please DO include the following sections
in your pull requests:
1. Reason for code modification. Include GitHub Issue # (create if not exists)
2. Supporting API version (3, 4 or both)
3. Manual test description: Method and result.
4. Risks of change.
## Code of Conduct
Please read and acknowledge our
[Code of Conduct](https://github.com/anelendata/PyPardotSF/blob/master/CODE_OF_CONDUCT.md).
before using or contributing to this project.
## Related projects
- target-pardot: A singer.io specification that bulk-updates prospect records
to Pardot. The program uses PyPardotSF.
# About this project
This project is developed by
ANELEN and friends. Please check out the ANELEN's
[open innovation philosophy and other projects](https://anelen.co/open-source.html)
---
Copyright © 2020~ Anelen Co., LLC
PyPardot4
=========
*This is README from the original PyPardot4 by Matt Needham, as of this [commit](5b26b871b7d4f6385755b2f3737a299509659ce1).*
PyPardot was originally created by Josh Geller as a wrapper for Version 3 of the Pardot API.
I, Matt Needham, have edited PyPardot for compatibility with Version 4 of the Pardot API.
Version 4 accommodates multiple prospects with the same email address. If your Pardot org does not have this featured enabled, you must use version 3.
To determine if your Pardot org has this feature enabled, [check out this guide](http://developer.pardot.com/kb/api-version-4/).
PyPardot is an API wrapper for [Pardot](http://www.pardot.com/), written in Python.
Using it is simple:
```python
from pypardot.client import PardotAPI
p = PardotAPI(
email='email@email.com',
password='password',
user_key='userkey'
)
p.authenticate()
# Create a new prospect
p.prospects.create(email='joe@company.com', first_name='Joe', last_name='Schmoe')
# Read data about our prospect
print(p.prospects.read_by_email(email='joe@company.com'))
```
Features
---
+ Includes all documented Pardot API operations
+ Handles API key expiration
+ Detailed API error handling
Object Types & Operations
---
Support for the following object types:
+ Accounts
+ Campaigns
+ Custom Fields
+ Custom Redirects
+ Dynamic Content
+ Emails
+ Email Clicks
+ Email Templates
+ Forms
+ Lifecycle Histories
+ Lifecycle Stages
+ Lists
+ List Memberships
+ Opportunities
+ Prospects
+ Prospect Accounts
+ Tags
+ TagObjects
+ Users
+ Visitor Activities
+ Visitors
+ Visits
Required
---
+ [requests](http://docs.python-requests.org/en/latest/)
Installation
---
Install PyPardot by running:
```shell
pip install pypardot4
```
Usage
---
### Authentication
To connect to the Pardot API, you'll need the e-mail address, password, and user key associated with your Pardot account. Your user key is available in the Pardot application under My Settings.
The client will authenticate before performing other API calls, but you can manually authenticate as well:
```python
p = PardotAPI(
email='your_pardot_email',
password='your_pardot_password',
user_key='your_pardot_user_key'
)
p.authenticate()
```
### Querying Objects
Supported search criteria varies for each object. Check the [official Pardot API documentation](http://developer.pardot.com/) for supported parameters. Most objects support `limit`, `offset`, `sort_by`, and `sort_order` parameters. PyPardot returns JSON for all API queries.
**Note**: Pardot only returns 200 records with each request. Use `offset` to retrieve matching records beyond this limit.
```python
# Query and iterate through today's prospects
prospects = p.prospects.query(created_after='yesterday')
total = prospects['total_results'] # total number of matching records
for prospect in prospects['prospect']
print(prospect.get('first_name'))
```
### Editing/Updating/Reading Objects
Supported fields varies for each object. Check the [official Pardot API documentation](http://developer.pardot.com/kb/object-field-references/) to see the fields associated with each object.
```python
# Create a new prospect
p.prospects.create_by_email(email='joe@company.com', first_name='Joe', last_name='Schmoe')
# Update a prospect field (works with default or custom field)
p.prospects.update_field_by_id(id=23839663, field_name='company', field_value='Joes Plumbing')
# Send a one-off email
p.emails.send_to_email(prospect_email='joe@company.com', email_template_id=123)
```
### Error Handling
#### Handling expired API keys
Pardot API keys expire after 60 minutes. If PyPardot detects an 'Invalid API key' error during any API call, it will automatically attempt to re-authenticate and obtain a new valid API key. If re-authentication is successful, the API call will be re-issued. If re-authentication fails, a `PardotAPIError` is thrown.
#### Invalid API parameters
If an API call is made with missing or invalid parameters, a `PardotAPIError` is thrown. Error instances contain the error code and message corresponding to error response returned by the API. See [Pardot Error Codes & Messages](http://developer.pardot.com/kb/error-codes-messages/) in the official documentation.
Performing API calls is inherently unsafe, so be sure to catch exceptions:
```python
try:
p.prospects.create_by_email(email='existing.email.address@company.com')
except PardotAPIError, e:
print(e)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/anelendata/PyPardotSF",
"name": "PyPardotSF",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "pardot",
"author": "Daigo Tanaka, Anelen Co., LLC",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/a1/ba/5e8623888e4a0a3b09d3b9ee0b60e8f31f4c9cf20d0cb4e29fb848d2af55/PyPardotSF-0.1.1.tar.gz",
"platform": null,
"description": "# PyPardotSF\n\nPyPardotSF is yet another fork of PyPardot/PyPardot4. The main driver for the\nfork is to address Pardot's authentication change in Spring 2021 to use\nSalesforce OAuth.\n(As seen on [PyPardot4 Issue #46](https://github.com/mneedham91/PyPardot4/issues/46))\n\nAnother new features of PyPardotSF includes:\n\n- Support both Versions 3 & 4 of Pardot API\n- Support Version 3 & 4 [Import API (for Prospects)](https://developer.salesforce.com/docs/marketing/pardot/guide/import-v4.html)\n\nThis is a working prototype and the code is currently being cleaned up and\nmore detailed documentation is underway.\n\nI'm keeping the original MIT License by the previous contributors.\nAny contributions, including code, documentations, issue reporting are welcome.\n\n## Install\n\n```\npip install PyPardotSF\n```\n\n## Salesforce OAuth\n\n### Get keys and tokens\n\nDo this once when you do not have consumer key, secret, refresh token:\n\n1. Open Python's interactive shell and run the following command:\n\n```\n$ python3\n\n>>> from pypardot.client import PardotAPI\n>>> p = PardotAPI(version=3) # verion=4 available\n>>> p.setup_salesforce_auth_keys()\n```\n\n2. Follow the instruction in the command line to get the keys and\nrefresh token.\n\n3. After you answer all the questions in the console, you should be able to\naccess API commands:\n\n```\n>>> p.prospects.read_by_email(email=\"daigo@anelen.co\")\n```\n\n4. You can check the values of business unit id, consumer key, secret, and\nrefresh token:\n\n```\n>>> p.business_unit_id\n'0Uv*****'\n>>> p.sf_consumer_key\n'xxxx'\n>>> p.sf_consumer_secret\n'yyyy'\n>>> p.sftoken_refresh\n'zzzz'\n```\n\n5. Please note them for the secondary and/or programmatic access.\n(See the next section)\n\n### Using the API client\n\n```\nfrom pypardot.client import PardotAPI\n\nversion = 3 # 3 or 4\nsf_consumer_key = \"xxxx\"\nsf_consumer_secret = \"yyyy\"\nsf_refresh_token = \"zzzz\"\nbusiness_unit_id = \"0Uv*****\"\n\np = PardotAPI(\n sf_consumer_key=sf_consumer_key,\n sf_consumer_secret=sf_consumer_secret,\n sf_refresh_token=sf_refresh_token,\n business_unit_id=business_unit_id,\n version=version)\np.prospects.read_by_email(email=\"daigo@anelen.co\")\n```\n\n## Bulk Prospect Import\n\n```\nfile_name = \"data.csv\"\ncolumns = [\n {\n \"field\": \"email\"\n },\n {\n \"field\": \"pardot_field_a\",\n \"overwrite\": False,\n \"nullOverwrite\": False\n },\n {\n \"field\": \"pardot_field_b\",\n \"overwrite\": False,\n \"nullOverwrite\": False\n },\n}\nresults = client.importapi.create(\n file_name=file_name,\n operation=\"Upsert\",\n object=\"Prospect\",\n columns=columns,\n restoreDeleted=config.get(\"restore_deleted\", False),\n )\nbatch_id = results[\"id\"]\nresults = client.importapi.update(id=batch_id, state=\"Ready\")\n```\n\nCheck the import status at:\n\nAPI Imports section at \n[Admin->Import->Prospects](https://pi.pardot.com/import/wizardStep1)\n\n## Other endpoints\n\nPlease see the original\n[PyPardot](https://github.com/joshgeller/PyPardot) /\n[PyPardot4](https://github.com/mneedham91/PyPardot4)\ndocs.\n\n## Contributors wanted\n\nMy (Daigo Tanaka) access to Pardot may not be permanent and I curently have\naccess to Ver 3 API. So I would like this repository to be collaborative as\npossible with the active Python programmers who uses Pardot API. This includes\nthe release process. I don't want to be a gate-keeper or a blocker.\n\nAny bug fixes and enhancements are welcome and I trust your good intentions.\nTogether with the fellow contributors, I will help review the code from\ngood design and coding stand point, but I may not be able to run tests myself\nfor the reason I stated above. So please DO include the following sections\nin your pull requests:\n\n1. Reason for code modification. Include GitHub Issue # (create if not exists)\n2. Supporting API version (3, 4 or both)\n3. Manual test description: Method and result.\n4. Risks of change.\n\n## Code of Conduct\n\nPlease read and acknowledge our\n[Code of Conduct](https://github.com/anelendata/PyPardotSF/blob/master/CODE_OF_CONDUCT.md).\nbefore using or contributing to this project.\n\n## Related projects\n\n- target-pardot: A singer.io specification that bulk-updates prospect records\n to Pardot. The program uses PyPardotSF.\n\n# About this project\n\nThis project is developed by \nANELEN and friends. Please check out the ANELEN's\n[open innovation philosophy and other projects](https://anelen.co/open-source.html)\n\n\n---\n\nCopyright © 2020~ Anelen Co., LLC\n\nPyPardot4\n=========\n\n*This is README from the original PyPardot4 by Matt Needham, as of this [commit](5b26b871b7d4f6385755b2f3737a299509659ce1).*\n\nPyPardot was originally created by Josh Geller as a wrapper for Version 3 of the Pardot API.\nI, Matt Needham, have edited PyPardot for compatibility with Version 4 of the Pardot API.\nVersion 4 accommodates multiple prospects with the same email address. If your Pardot org does not have this featured enabled, you must use version 3.\nTo determine if your Pardot org has this feature enabled, [check out this guide](http://developer.pardot.com/kb/api-version-4/).\n\nPyPardot is an API wrapper for [Pardot](http://www.pardot.com/), written in Python.\n\nUsing it is simple:\n\n```python\nfrom pypardot.client import PardotAPI\n\np = PardotAPI(\n email='email@email.com',\n password='password',\n user_key='userkey'\n)\n \np.authenticate()\n\n# Create a new prospect\np.prospects.create(email='joe@company.com', first_name='Joe', last_name='Schmoe')\n\n# Read data about our prospect\nprint(p.prospects.read_by_email(email='joe@company.com'))\n\n```\n\nFeatures\n---\n\n+ Includes all documented Pardot API operations\n+ Handles API key expiration\n+ Detailed API error handling\n\nObject Types & Operations\n---\n\nSupport for the following object types:\n\n+ Accounts\n+ Campaigns\n+ Custom Fields\n+ Custom Redirects\n+ Dynamic Content\n+ Emails\n+ Email Clicks\n+ Email Templates\n+ Forms\n+ Lifecycle Histories\n+ Lifecycle Stages\n+ Lists\n+ List Memberships\n+ Opportunities\n+ Prospects\n+ Prospect Accounts\n+ Tags\n+ TagObjects\n+ Users\n+ Visitor Activities\n+ Visitors\n+ Visits\n\nRequired\n---\n\n+ [requests](http://docs.python-requests.org/en/latest/)\n\nInstallation\n---\n\nInstall PyPardot by running:\n```shell\npip install pypardot4\n```\n\nUsage\n---\n\n### Authentication\n\nTo connect to the Pardot API, you'll need the e-mail address, password, and user key associated with your Pardot account. Your user key is available in the Pardot application under My Settings.\n\nThe client will authenticate before performing other API calls, but you can manually authenticate as well:\n\n\n```python\np = PardotAPI(\n email='your_pardot_email',\n password='your_pardot_password',\n user_key='your_pardot_user_key'\n)\n \np.authenticate()\n```\n\n### Querying Objects\n\nSupported search criteria varies for each object. Check the [official Pardot API documentation](http://developer.pardot.com/) for supported parameters. Most objects support `limit`, `offset`, `sort_by`, and `sort_order` parameters. PyPardot returns JSON for all API queries.\n\n**Note**: Pardot only returns 200 records with each request. Use `offset` to retrieve matching records beyond this limit.\n\n```python\n# Query and iterate through today's prospects\nprospects = p.prospects.query(created_after='yesterday')\ntotal = prospects['total_results'] # total number of matching records\nfor prospect in prospects['prospect']\n print(prospect.get('first_name'))\n```\n\n### Editing/Updating/Reading Objects\n\nSupported fields varies for each object. Check the [official Pardot API documentation](http://developer.pardot.com/kb/object-field-references/) to see the fields associated with each object. \n\n```python\n# Create a new prospect\np.prospects.create_by_email(email='joe@company.com', first_name='Joe', last_name='Schmoe')\n\n# Update a prospect field (works with default or custom field)\np.prospects.update_field_by_id(id=23839663, field_name='company', field_value='Joes Plumbing')\n\n# Send a one-off email\np.emails.send_to_email(prospect_email='joe@company.com', email_template_id=123)\n```\n\n### Error Handling\n\n#### Handling expired API keys\n\nPardot API keys expire after 60 minutes. If PyPardot detects an 'Invalid API key' error during any API call, it will automatically attempt to re-authenticate and obtain a new valid API key. If re-authentication is successful, the API call will be re-issued. If re-authentication fails, a `PardotAPIError` is thrown.\n\n#### Invalid API parameters\n\nIf an API call is made with missing or invalid parameters, a `PardotAPIError` is thrown. Error instances contain the error code and message corresponding to error response returned by the API. See [Pardot Error Codes & Messages](http://developer.pardot.com/kb/error-codes-messages/) in the official documentation.\n\nPerforming API calls is inherently unsafe, so be sure to catch exceptions:\n\n```python\ntry:\n p.prospects.create_by_email(email='existing.email.address@company.com')\nexcept PardotAPIError, e:\n print(e)\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "API wrapper for API v3 & v4 of Pardot marketing automation software.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/anelendata/PyPardotSF"
},
"split_keywords": [
"pardot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "36db09065c3999e242bfa09d3a0eac5f67dc1e27d270892e13fa016593623be8",
"md5": "68d8e78d49dd3d5cb91db8d47533976d",
"sha256": "e6010e0d6d70c892681b6a0672691544a14438aaeeb394b6b6390e38adcdee69"
},
"downloads": -1,
"filename": "PyPardotSF-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68d8e78d49dd3d5cb91db8d47533976d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 43370,
"upload_time": "2024-01-18T02:43:04",
"upload_time_iso_8601": "2024-01-18T02:43:04.382955Z",
"url": "https://files.pythonhosted.org/packages/36/db/09065c3999e242bfa09d3a0eac5f67dc1e27d270892e13fa016593623be8/PyPardotSF-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1ba5e8623888e4a0a3b09d3b9ee0b60e8f31f4c9cf20d0cb4e29fb848d2af55",
"md5": "78f6dab3fb8f73cb1bf51576b7af368b",
"sha256": "3888404b72a43e9ef4cfa7f28c8f621a12e73a8f9c6e801b23d4261aff27afa6"
},
"downloads": -1,
"filename": "PyPardotSF-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "78f6dab3fb8f73cb1bf51576b7af368b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21834,
"upload_time": "2024-01-18T02:43:06",
"upload_time_iso_8601": "2024-01-18T02:43:06.099269Z",
"url": "https://files.pythonhosted.org/packages/a1/ba/5e8623888e4a0a3b09d3b9ee0b60e8f31f4c9cf20d0cb4e29fb848d2af55/PyPardotSF-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 02:43:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anelendata",
"github_project": "PyPardotSF",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pypardotsf"
}
JSON
