A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The GetResponse API is how an app or AI agent works with a GetResponse account: adding and updating contacts, building segments, sending newsletters, and running autoresponders and automation workflows. Access is granted through an API key or an OAuth token, which on GetResponse reaches the whole account rather than a chosen subset, since the key carries a single all-data permission and not per-area scopes. GetResponse can also push contact activity to a callback URL when someone subscribes, opens a message, or clicks a link.
How an app or AI agent connects to GetResponse determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the key or token behind it, which on GetResponse carries access to the whole account.
The REST API answers at https://api.getresponse.com/v3, takes and returns JSON, and pages lists with page and perPage query parameters. GetResponse MAX accounts use a different host, https://api3.getresponse360.com/v3 or https://api3.getresponse360.pl/v3, and add an X-Domain header. A call authenticates with an API key in the X-Auth-Token header or an OAuth bearer token.
GetResponse POSTs a contact-activity event to a callback URL set on the account, for activity like subscribe, unsubscribe, open, click, goal, and survey. The callback timeout is 4 seconds, and a callback that is not received in time is dropped and not retried, so the receiver must respond quickly. Callbacks are configured through the account callbacks endpoint or in the web interface.
An API key is created in the account and sent in the X-Auth-Token header, prefixed with 'api-key', as in 'X-Auth-Token: api-key {key}'. The key reaches the whole account, since GetResponse does not scope a key to a subset of data or to particular endpoints. An unused key expires after 90 days.
OAuth 2.0 issues a bearer token sent in the Authorization header. GetResponse supports the authorization-code, client-credentials, and implicit flows, and the only scope it offers is 'all', which grants access to all account data. It suits an app connecting to many accounts without holding each one's raw key.
The GetResponse API is split into areas an agent can act on, like contacts, lists, newsletters, autoresponders, and automation workflows. Each area has its own methods, and writes in some areas send email to real subscribers or change who is on a list.
List, read, create, update, and delete contacts, add them in batches, and read their activity and consent history.
Run a search over contacts, and save, read, update, and delete the saved segments those searches define.
List, read, create, and update lists, read the contacts on a list, and pull subscriber statistics.
List, read, create, update, and delete the custom field definitions that hold extra data on a contact.
List, read, create, update, and delete tags used to label and segment contacts.
List, read, create, and send newsletters, send a saved draft, cancel a send, and read send statistics.
List, read, create, update, and delete autoresponders, the scheduled messages a contact receives over a cycle.
List and read automation workflows, and update an existing workflow.
List and read forms and their A/B variants, and list and read landing pages.
Send a transactional email, manage transactional templates, and read transactional send statistics.
List, create, update, and delete custom events, and trigger one to start automation.
Read account details, and read, enable, update, or disable the account's callback (webhook) configuration.
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 | |
|---|---|---|---|---|---|---|
ContactsList, read, create, update, and delete contacts, add them in batches, and read their activity and consent history.8 | ||||||
| GET | /contacts | Get a list of contacts in the account. | read | — | Current | |
Reads contacts across the account; GetResponse does not scope keys to a subset of data. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /contacts/{contactId} | Get the details of a single contact by contact ID. | read | — | Current | |
Read-only. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts | Create a new contact. Email and a list (campaign) are the minimum required. | write | — | Current | |
Adding a contact to a list with confirmed opt-in can send a confirmation email. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts/batch | Create multiple contacts at once in a single batch request. | write | — | Current | |
Processed asynchronously; the batch can add many contacts in one call. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts/{contactId} | Update the details of an existing contact. | write | — | Current | |
GetResponse uses POST, not PATCH, to update a contact. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /contacts/{contactId} | Delete a contact by contact ID. | write | — | Current | |
Removes the contact from the list. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event unsubscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts/{contactId}/tags | Add or update the tags applied to a contact. | write | — | Current | |
Upserts tags; tags must already exist as definitions. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /contacts/{contactId}/activities | Get a list of a contact's activities, like opens and clicks. | read | — | Current | |
Read-only. Acts oncontact activity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Segments (search contacts)Run a search over contacts, and save, read, update, and delete the saved segments those searches define.4 | ||||||
| POST | /search-contacts/contacts | Search contacts using a set of conditions, without saving a segment. | read | — | Current | |
A read that uses POST to carry the search query in the body. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /search-contacts | Get a list of saved segments (saved searches). | read | — | Current | |
Read-only. Acts onsegment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /search-contacts | Create a saved segment from a set of search conditions. | write | — | Current | |
Saves the search so it can be reused. Acts onsegment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /search-contacts/{searchContactId}/contacts | Get the contacts that match a saved segment. | read | — | Current | |
Read-only; results are paginated. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Lists (campaigns)List, read, create, and update lists, read the contacts on a list, and pull subscriber statistics.5 | ||||||
| GET | /campaigns | Get a list of lists (campaigns) in the account. | read | — | Current | |
A campaign in the API is a contact list in the GetResponse interface. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /campaigns/{campaignId} | Get a single list (campaign) by campaign ID. | read | — | Current | |
Read-only. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /campaigns | Create a new list (campaign). | write | — | Current | |
Creates a list contacts can be added to. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /campaigns/{campaignId} | Update a list's (campaign's) settings. | write | — | Current | |
GetResponse uses POST, not PATCH, to update a campaign. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /campaigns/{campaignId}/contacts | Get the contacts on a single list (campaign). | read | — | Current | |
Read-only; results are paginated. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom fieldsList, read, create, update, and delete the custom field definitions that hold extra data on a contact.4 | ||||||
| GET | /custom-fields | Get a list of custom field definitions. | read | — | Current | |
Read-only. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /custom-fields | Create a custom field definition. | write | — | Current | |
Defines a new field that can hold extra data on contacts. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /custom-fields/{customFieldId} | Update a custom field definition. | write | — | Current | |
Changes the definition, which affects every contact that uses the field. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /custom-fields/{customFieldId} | Delete a custom field definition. | write | — | Current | |
Removes the field and its values from contacts. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList, read, create, update, and delete tags used to label and segment contacts.3 | ||||||
| GET | /tags | Get a list of tags. | read | — | Current | |
Read-only. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tags | Add a new tag. | write | — | Current | |
Creates a tag definition that can then be applied to contacts. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /tags/{tagId} | Delete a tag by ID. | write | — | Current | |
Removes the tag from every contact it was applied to. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NewslettersList, read, create, and send newsletters, send a saved draft, cancel a send, and read send statistics.5 | ||||||
| GET | /newsletters | Get the list of newsletters. | read | — | Current | |
Read-only. Acts onnewsletter Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /newsletters | Create a newsletter and send or schedule it to lists and segments. | write | — | Current | |
Depending on the send settings, this emails real subscribers. Acts onnewsletter Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /newsletters/send-draft | Send a saved newsletter draft. | write | — | Current | |
Sends an existing draft to its recipients. Acts onnewsletter Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /newsletters/{newsletterId}/cancel | Cancel sending a newsletter that has not finished sending. | write | — | Current | |
Only works while the newsletter is still in a cancellable state. Acts onnewsletter Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /newsletters/{newsletterId}/statistics | Get the send statistics for a single newsletter. | read | — | Current | |
Read-only. Acts onnewsletter statistics Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AutorespondersList, read, create, update, and delete autoresponders, the scheduled messages a contact receives over a cycle.4 | ||||||
| GET | /autoresponders | Get the list of autoresponders. | read | — | Current | |
Read-only. Acts onautoresponder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /autoresponders | Create an autoresponder message in a sending cycle. | write | — | Current | |
An active autoresponder emails contacts on the configured day of the cycle. Acts onautoresponder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /autoresponders/{autoresponderId} | Update an autoresponder. | write | — | Current | |
Changes a message that may already be sending automatically. Acts onautoresponder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /autoresponders/{autoresponderId} | Delete an autoresponder. | write | — | Current | |
Stops the message from being sent in its cycle. Acts onautoresponder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Automation workflowsList and read automation workflows, and update an existing workflow.3 | ||||||
| GET | /workflow | Get a list of automation workflows. | read | — | Current | |
Read-only. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflow/{workflowId} | Get a single automation workflow by ID. | read | — | Current | |
Read-only. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflow/{workflowId} | Update an automation workflow. | write | — | Current | |
Changes live automation that can email and tag contacts. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Forms & landing pagesList and read forms and their A/B variants, and list and read landing pages.4 | ||||||
| GET | /forms | Get the list of forms. | read | — | Current | |
Read-only. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /forms/{formId} | Get a single form by ID. | read | — | Current | |
Read-only. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /landing-pages | Get a list of landing pages. | read | — | Current | |
Read-only. Acts onlanding page Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /landing-pages/{landingPageId} | Get a single landing page by ID. | read | — | Current | |
Read-only. Acts onlanding page Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Transactional emailsSend a transactional email, manage transactional templates, and read transactional send statistics.3 | ||||||
| POST | /transactional-emails | Send a transactional email to a recipient. | write | — | Current | |
Transactional emails require GetResponse MAX and a Transactional Emails add-on. Acts ontransactional email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /transactional-emails | Get the list of transactional emails. | read | — | Current | |
Read-only; GetResponse MAX feature. Acts ontransactional email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /transactional-emails/templates | Create a transactional email template. | write | — | Current | |
GetResponse MAX feature. Acts ontransactional email template Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom eventsList, create, update, and delete custom events, and trigger one to start automation.2 | ||||||
| GET | /custom-events | Get a list of custom events used to start automation. | read | — | Current | |
Read-only. Acts oncustom event Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /custom-events/trigger | Trigger a custom event for a contact to start automation. | write | — | Current | |
Can start live automation that emails and tags the contact. Acts oncustom event Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Account & callbacksRead account details, and read, enable, update, or disable the account's callback (webhook) configuration.3 | ||||||
| GET | /accounts | Get information about the authenticated account. | read | — | Current | |
Read-only. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/callbacks | Get the account's callback (webhook) configuration. | read | — | Current | |
Read-only. Acts oncallback Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/callbacks | Enable or update the account's callback (webhook) configuration. | write | — | Current | |
Sets the URL GetResponse posts contact-activity events to. Acts oncallback Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GetResponse can notify an app or AI agent when a contact acts, like subscribing, opening a message, or clicking a link. It posts the event to a callback URL set on the account, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
subscribe | Fires when a contact is added to a list, for example through the API, a form, or an import. | /contacts/contacts/batch |
unsubscribe | Fires when a contact is removed from a list or unsubscribes. | /contacts/{contactId} |
open | Fires when a contact opens a message. | In-app only |
click | Fires when a contact clicks a tracked link in a message. | In-app only |
goal | Fires when a contact reaches a tracked goal, like visiting a configured page. | In-app only |
survey | Fires when a contact completes a survey. | In-app only |
GetResponse limits how fast and how much an app or AI agent can call, through a per-key request quota measured over a fixed time window and a separate cap on how many requests run at once.
GetResponse meters requests per API key over a fixed 10-minute time frame. Each key may make 30,000 calls per time frame and 80 calls per second, and may run up to 10 requests at once. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers reporting the quota, the requests left, and the seconds until the window resets. Going over returns HTTP 429 with error code 1015 and currentLimit and timeToReset values in the body.
List endpoints use page-number pagination through the page and perPage query parameters, as in ?page=2&perPage=100. perPage tops out at 1,000 on most endpoints and defaults to a smaller page. Some list endpoints also accept sort and query filters to narrow results before paging.
Responses are JSON. A list page returns at most 1,000 items, the maximum value of perPage. The contacts batch endpoint accepts many contacts in one request and processes them asynchronously rather than returning them inline.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | 1000 | A general validation error. The request had one or more invalid fields, listed in the context array of the error body. | Read the context entries, correct the named fields, and resend. |
| 400 | 1001 | A related resource referenced in the request could not be found, for example a campaign ID that does not exist. | Check the referenced IDs exist and belong to this account, then resend. |
| 400 | 1002 | The resource is in a state that forbids the requested action. | Refetch the resource, check its state, and retry the action only when it is allowed. |
| 403 | 1014 | Authentication or authorization failed. The API key or token is missing, invalid, or expired. | Confirm a valid key or token is sent in the right header, and regenerate the key if it has expired. |
| 404 | 1013 | There is no resource of the given ID. | Verify the ID and that it belongs to this account. |
| 409 | 1008 | A unique property already has the submitted value, like a duplicate that conflicts with an existing record. | Use a value that does not already exist, or update the existing record instead. |
| 429 | 1015 | The rate limit was exceeded, or the request looked suspicious. The body carries currentLimit and timeToReset values. | Back off until timeToReset, then retry, and smooth the request rate. |
| 500 | 1 | Something went wrong on GetResponse's side. It is rare and not caused by the request. | Retry after a short wait, and contact GetResponse support if it persists. |
GetResponse versions its API by a single major number in the path. The current version is v3, and GetResponse increments the number only when it ships a change that is not backward compatible.
GetResponse versions its API by a single major number in the path, currently v3. GetResponse states it will increment the number only when it ships a backward-incompatible change, so new resources and fields are added under v3 without minting a new version. The published OpenAPI specification carried a dated build stamp of 2026-04-28 when last checked. There is no dated version header to pin and no public dated API changelog, so feature changes are tracked through the product 'what's new' page rather than an API release log.
Shopify customer tags now sync automatically into GetResponse on paid plans, feeding segmentation and automation triggers. This is a product feature reachable through the contacts, tags, and automation areas of the API rather than a new API version.
Revenue attribution connects emails and workflows to purchases, surfacing attributed revenue, orders, and average order value per message. The figures are read through the ecommerce statistics endpoints.
Automation workflows gained a toggle to exclude automated systems like email security scanners and antivirus software from triggering on opens and clicks, which affects how callback and automation activity is counted.
Build against v3 and watch the developer docs for any future major version.
GetResponse what's new ↗Bollard AI sits between a team's AI agents and GetResponse. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.