A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Drip API is how an app or AI agent works with a Drip account: adding and updating subscribers, applying and removing tags, recording events, subscribing people to campaigns and workflows, and sending broadcasts. Access is granted through an API token or an OAuth connection, and that credential reaches everything in the accounts it belongs to, because Drip has no granular per-endpoint permissions. Drip can also push subscriber activity, like a tag being applied or an email being clicked, to a registered webhook.
How an app or AI agent connects to Drip determines what it can reach. There is a route for making calls and a route for receiving events, each governed by the token behind it. A Drip token reaches everything in the accounts it belongs to, because access is account-level, so the boundary is set outside Drip.
The REST API answers at https://api.getdrip.com over HTTPS, taking JSON request bodies and returning JSON. Most resources sit under the v2 path, while the newer shopper-activity endpoints for orders, carts, and products sit under v3. A call authenticates with an API token or an OAuth 2.0 token.
Drip posts a JSON payload to a registered URL when a chosen subscriber event happens, such as a tag being applied or an email being clicked. Webhooks are created through the API or in the Drip settings, and are filtered to the events they should receive.
A private-integration API token authenticates with HTTP Basic auth, sent as the username with an empty password. The token reaches every account and resource it belongs to, because Drip has no granular per-endpoint permissions. It is meant for server-side calls and must be kept secret.
A public integration uses the OAuth 2.0 authorization-code flow at getdrip.com to connect to accounts it does not own, exchanging the code for a Bearer access token. Drip states the token does not expire. The grant is account-level, with no per-resource scopes to narrow it.
The Drip API is split into areas an agent can act on, like subscribers, events, tags, campaigns, workflows, and orders. Each area has its own methods, and writes in some areas send email to real people or remove subscriber records.
List subscribers, fetch one, create or update a subscriber, delete a subscriber, and unsubscribe people in bulk.
Record a custom event for a subscriber, record events in bulk, and list the custom event actions an account has seen.
List the tags in an account, apply a tag to a subscriber, and remove a tag from a subscriber.
List and read email-series campaigns, subscribe a person to one, and list or remove its subscribers.
List and read workflows, start a subscriber in one, and remove a subscriber from one.
List, read, create, update, and delete single-email campaigns, and send a test of one.
List the custom field identifiers an account uses on its subscribers.
Record orders for subscribers in bulk through the shopper-activity API.
List and read an account's webhooks, create a webhook, and delete one.
List the accounts a token can reach and fetch a single account's details.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SubscribersList subscribers, fetch one, create or update a subscriber, delete a subscriber, and unsubscribe people in bulk.6 | ||||||
| GET | /v2/:account_id/subscribers | List all subscribers in an account. | read | — | Current | |
Drip access is account-level, so any valid token for the account can read its subscribers; there is no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/subscribers/:subscriber_id | Fetch a single subscriber by id or email address. | read | — | Current | |
Returns the subscriber's email, custom fields, tags, and status. Account-level access, no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/subscribers | Create a subscriber, or update an existing one matched by email or id. | write | — | Current | |
A single create-or-update call; sets custom fields, tags, and status in one request. Account-level access, no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/subscribers/batches | Create or update up to 1,000 subscribers in one batch request. | write | — | Current | |
Processed asynchronously and counted against the separate 50-per-hour batch quota. Account-level access, no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitBatch quota: 50 requests per hour, up to 1,000 records each SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/unsubscribes/batches | Unsubscribe up to 1,000 people from all mailings in one batch request. | write | — | Current | |
Marks people as unsubscribed from email marketing rather than deleting them. Counted against the batch quota. Account-level access, no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.unsubscribed_allRate limitBatch quota: 50 requests per hour, up to 1,000 records each SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/:account_id/subscribers/:subscriber_id | Permanently delete a subscriber from an account. | write | — | Current | |
Irreversible; removes the person and their history. Account-level access, no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsRecord a custom event for a subscriber, record events in bulk, and list the custom event actions an account has seen.3 | ||||||
| POST | /v2/:account_id/events | Record a custom event for a subscriber, such as a product viewed or a feature used. | write | — | Current | |
An event can start a workflow or campaign that acts on the subscriber. Account-level access, no per-endpoint scope. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.performed_custom_eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/events/batches | Record up to 1,000 custom events in one batch request. | write | — | Current | |
Processed asynchronously and counted against the batch quota. Account-level access, no per-endpoint scope. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitBatch quota: 50 requests per hour, up to 1,000 records each SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/event_actions | List the custom event actions an account has recorded. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onevent action Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList the tags in an account, apply a tag to a subscriber, and remove a tag from a subscriber.3 | ||||||
| GET | /v2/:account_id/tags | List all tags in an account. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/subscribers/:subscriber_id/tags | Apply a tag to a subscriber. | write | — | Current | |
Applying a tag can start or stop an automation. Account-level access, no per-endpoint scope. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.applied_tagRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/:account_id/subscribers/:subscriber_id/tags/:tag | Remove a tag from a subscriber. | write | — | Current | |
Account-level access, no per-endpoint scope. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.removed_tagRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CampaignsList and read email-series campaigns, subscribe a person to one, and list or remove its subscribers.5 | ||||||
| GET | /v2/:account_id/campaigns | List the email-series campaigns in an account. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/campaigns/:campaign_id | Fetch a single email-series campaign. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/campaigns/:campaign_id/subscribers | Subscribe a person to an email-series campaign. | write | — | Current | |
Adds a real person to an email series that will send to them. Account-level access, no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.subscribed_to_campaignRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/campaigns/:campaign_id/subscribers | List the subscribers of an email-series campaign. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/subscribers/:subscriber_id/remove | Remove a subscriber from a campaign, or from all of an account's email. | write | — | Current | |
A campaign_id parameter limits the removal to one campaign; without it the person is removed from all campaigns. Account-level access, no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscriber.removed_from_campaignRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkflowsList and read workflows, start a subscriber in one, and remove a subscriber from one.4 | ||||||
| GET | /v2/:account_id/workflows | List the workflows in an account. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/workflows/:workflow_id | Fetch a single workflow. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/workflows/:workflow_id/subscribers | Start a subscriber in a workflow. | write | — | Current | |
Moves a real person into an automation that acts on them. Account-level access, no per-endpoint scope. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/:account_id/workflows/:workflow_id/subscribers/:subscriber_id | Remove a subscriber from a workflow. | write | — | Current | |
Account-level access, no per-endpoint scope. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BroadcastsList, read, create, update, and delete single-email campaigns, and send a test of one.6 | ||||||
| GET | /v2/:account_id/broadcasts | List the single-email campaigns (broadcasts) in an account. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onbroadcast Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/broadcasts/:broadcast_id | Fetch a single broadcast. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onbroadcast Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/broadcasts | Create a single-email campaign (broadcast). | write | — | Current | |
Creates an email that can be sent to real people. Account-level access, no per-endpoint scope. Acts onbroadcast Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/:account_id/broadcasts/:broadcast_id | Update a broadcast. | write | — | Current | |
Account-level access, no per-endpoint scope. Acts onbroadcast Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/:account_id/broadcasts/:broadcast_id | Delete a broadcast. | write | — | Current | |
Account-level access, no per-endpoint scope. Acts onbroadcast Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/broadcasts/:broadcast_id/send_test | Send a test of a broadcast to chosen addresses. | write | — | Current | |
Sends a real email to the test addresses. Account-level access, no per-endpoint scope. Acts onbroadcast Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom fieldsList the custom field identifiers an account uses on its subscribers.1 | ||||||
| GET | /v2/:account_id/custom_field_identifiers | List the custom field identifiers used on an account's subscribers. | read | — | Current | |
Custom field values themselves are set on the subscriber. Account-level access, no per-endpoint scope. Acts oncustom field identifier Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Orders (ecommerce)Record orders for subscribers in bulk through the shopper-activity API.1 | ||||||
| POST | /v3/:account_id/shopper_activity/order/batch | Record up to 1,000 orders for subscribers in one batch request. | write | — | Current | |
The newer shopper-activity order endpoint answers under v3. Processed asynchronously and counted against the batch quota. Account-level access, no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitBatch quota: 50 requests per hour, up to 1,000 records each SourceOfficial documentation ↗ | ||||||
WebhooksList and read an account's webhooks, create a webhook, and delete one.4 | ||||||
| GET | /v2/:account_id/webhooks | List an account's webhooks. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/:account_id/webhooks/:webhook_id | Fetch a single webhook. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/:account_id/webhooks | Create a webhook that posts chosen events to a URL. | write | — | Current | |
Sets where Drip sends a copy of account activity. Account-level access, no per-endpoint scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/:account_id/webhooks/:webhook_id | Delete a webhook. | write | — | Current | |
Account-level access, no per-endpoint scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsList the accounts a token can reach and fetch a single account's details.2 | ||||||
| GET | /v2/accounts | List the accounts the authenticated token can reach. | read | — | Current | |
Not scoped to an account_id, since it lists the accounts the token belongs to. Account-level access, no per-endpoint scope. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/:account_id | Fetch a single account's details. | read | — | Current | |
Account-level access, no per-endpoint scope. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Drip can notify an app or AI agent when something happens to a subscriber, like a tag being applied, an email being clicked, or a custom event being recorded. Drip posts a JSON payload to a webhook URL that has been registered for the chosen events.
| Event | What it signals | Triggered by |
|---|---|---|
subscriber.created | Fires when a subscriber is created in the account. | /v2/:account_id/subscribers |
subscriber.deleted | Fires when a subscriber is permanently deleted. | /v2/:account_id/subscribers/:subscriber_id |
subscriber.applied_tag | Fires when a tag is applied to a subscriber. | /v2/:account_id/subscribers/:subscriber_id/tags |
subscriber.removed_tag | Fires when a tag is removed from a subscriber. | /v2/:account_id/subscribers/:subscriber_id/tags/:tag |
subscriber.subscribed_to_campaign | Fires when a subscriber is subscribed to an email-series campaign. | /v2/:account_id/campaigns/:campaign_id/subscribers |
subscriber.removed_from_campaign | Fires when a subscriber is removed from a campaign. | /v2/:account_id/subscribers/:subscriber_id/remove |
subscriber.unsubscribed_all | Fires when a subscriber is unsubscribed from all of the account's email. | /v2/:account_id/unsubscribes/batches |
subscriber.performed_custom_event | Fires when a custom event is recorded for a subscriber. | /v2/:account_id/events |
subscriber.opened_email | Fires when a subscriber opens an email Drip sent them. | In-app only |
subscriber.clicked_email | Fires when a subscriber clicks a link in an email Drip sent them. | In-app only |
subscriber.bounced | Fires when an email to a subscriber bounces. | In-app only |
subscriber.updated_custom_field | Fires when a custom field on a subscriber changes. | In-app only |
Drip limits how fast an app or AI agent can call, through an hourly request quota that is counted separately for batch endpoints and for every other endpoint.
Drip counts requests per hour against two separate quotas. Regular endpoints allow 3,600 requests per hour, about one per second sustained. Batch endpoints, which take up to 1,000 records in a single call, have their own quota of 50 requests per hour, for up to 50,000 records an hour. The X-RateLimit-Limit and X-RateLimit-Remaining response headers report the current state, and exceeding either quota returns 429 with a message to try again in an hour.
List endpoints return up to 100 records per page by default, which is also the maximum, and take a page parameter to move through the pages.
A batch request carries up to 1,000 records in one call. Batch calls are processed asynchronously, so a change may take a moment to appear after the API accepts the request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | Authentication failed, because the API token or OAuth token is missing, invalid, or expired. | Send a valid token, as the Basic auth username for an API token or as a Bearer token for OAuth. |
| 403 | authorization_error | The request is authenticated but not permitted, for example acting on an account the token cannot reach, or a state transition that is not allowed. | Confirm the token belongs to the account, and that the resource is in a state that allows the action. |
| 404 | not_found_error | The requested resource does not exist in the account. | Check the account_id and resource id in the path. |
| 422 | validation error | The request was well-formed but a field is missing or invalid. The body holds an errors array with codes such as presence_error, email_error, length_error, and format_error. | Read the errors array, correct the named field, and resend. |
| 429 | rate limit exceeded | The hourly request quota was exceeded, returning the message that the rate limit is reached and to try again in an hour. | Wait for the quota to reset, and watch the X-RateLimit-Remaining header to stay under the limit. |
Drip versions its API in the path. Most resources answer under v2, while the newer shopper-activity endpoints for orders, carts, and products answer under v3.
The Drip REST API answers at api.getdrip.com. Most resources, including subscribers, events, tags, campaigns, workflows, broadcasts, custom fields, and webhooks, sit under the v2 path. The newer shopper-activity endpoints for orders, carts, and products sit under v3. Drip versions its API in the URL path rather than by date or header, so there is no per-account version to pin; dated changes ship through the product release notes.
Drip added a new API endpoint that returns Single Email Campaign metrics, exposing the same delivery and revenue data shown on the dashboard, like sends, deliveries, unsubscribes, bounces, complaints, orders, and revenue. The Orders batch endpoint was improved for importing large collections of orders that would exceed the 3,600-per-hour regular limit, and a bug where a failed POST to the batches endpoint still returned a 201 Created response was fixed.
Most integrations use v2 and move individual ecommerce calls to v3 where Drip has published the newer endpoint.
Drip API reference ↗Bollard AI sits between a team's AI agents and Drip. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.