# GetResponse REST Web Service Interface GetResponse API gives you basically the same functionality as in our web panels - you can perform the same set of actions: manage campaigns, newsletters, gather statistics and more (and yes we have segments in here!). ## API Endpoint Api endpoint (or base url) is always the same for all retail users and looks like follows: ``` https://api.getresponse.com/v3 ``` The only thing to remember is that the last part of it (v3 in this case) is the version number of our API. If in the future we introduce some backward incompatible changes we will increment our API version to give you time to migrate from v3 to (let's say) v4. But don't worry we will keep stable version for a long time and most of future updates will be backward compatible. ## GetResponse MAX platform For GetResponse MAX platform users endpoint looks different. There are two different url's and any GetResponse MAX user who wants to connect to our api should contact his account manager and which one he should use. - ```https://api3.getresponse360.pl/v3``` - ```https://api3.getresponse360.com/v3``` ## Authentication All request you want to send to our API must contain authentication information. For example, if your api-key is: `84fsne83yrths947r6sfgg7w4he8`, then the custom authentication header should look like: ``` X-Auth-Token: api-key 84fsne83yrths947r6sfgg7w4he8 ``` **For security reasons, unused API keys expire after 90 days. When that happens, you’ll need to generate a new key to use our API.** For more detailed information, mobile authentication and GetResponse MAX platform authentication please, go to our [authentication](authentication.md) page ## Basics This is REST API, all request follows REST rules in terms of resource naming convention, use of HTTP method as action description and use of custom headers to convey additional infomration. In order to correctly configure your app you need to remember couple of things. ### Methods (HTTPS) We accept 3 methods GET, POST and DELETE. Every POST request **MUST HAVE** Content-Type header. Currently we accept only 'application/json' content-type GET if to obtain information. There should not be any "body" data sent with that request. This will not trigger error, but we just simply don't look there in GET request. Only query string parameters ale allowed. This request will never change anything, you can call it as many times as you want. It is called that GET is IDEMPOTENT request. POST is to add new or modify existing information. If request url doesn't contain resource ID then we will treat that as new data that must be inserted. If you want to modify existing data you need to specify an ID in the Rrequest URL (like POST /contacts/hg5fF). POST is NOT IDEMPOTENT, you need to be carefull to not send the same request twice... DELETE is only to remove infomration. As a general rule we do not allow to add any "body" data to that type of request nor we allow any query string. This should be just simply DELETE /contacts/hg5fF. ### Resources and Representations We present data as JSON strings. Those information are named "representation" of a "resource". Each url in our API represents an "resource". Each representation has its own unique ID - naming convention is very easy: ID of a newsletters is called newsletterId :). We stick to json **camelCase** for field names in json data. When you call **GET /newsletters/V** we will return json data which represents a resource called "newsletter" where it's ID is equal to 'V'.  When you call GET /newsletters we will return a **Collection** of resources. This is simply a list of resources representations presented as json array. You need to remember that in a collection we could ommit some of the fileds that are there in single resource. You should treat collection as a brief information of a resource not a full package :). When you call POST /newsletters you need to send to us the same structure of json-encoded representation of a newsletter resource. This is very important! If you change name of a field, add some new fields of ommit some of the mandatory fields we will return 400 response with special "error" resource which will contain all validation errors that we discovered in your request. Sometimes you can ommit the field (if it isn't mandatory), but if you set some field with empty value we will treat this as normal and simply set this value to empty string or null. If you don't want to modify some field just don't include it in json representation. --- # Quick Start The shortest path to a working GetResponse API integration for AI agents and developers. Create your first campaign (contact list), then read it back. If both requests succeed, your integration is working and you’re ready to explore the [API Reference](https://apireference.getresponse.com/). ## Prerequisites - An API key generated in your account: [https://app.getresponse.com/api](https://app.getresponse.com/api) - Every request must include your API key in the `X-Auth-Token` header, prefixed with `api-key`. Replace `YOUR_API_KEY` with the API key from your account: ``` X-Auth-Token: api-key YOUR_API_KEY ``` - Base URL (use the base URL that corresponds to your account type): | Account type | Base URL | | --- | --- | | GetResponse (SMB) | `https://api.getresponse.com/v3` | | GetResponse MAX (PL) | `https://api3.getresponse360.pl/v3` | | GetResponse MAX (US) | `https://api3.getresponse360.com/v3` | **For MAX accounts:** Ask your account manager if you don’t know which domain your account is hosted on. MAX requests must also include an `X-Domain` header with your account domain, e.g. `X-Domain: example.com`. See [Authentication](authentication) for details. **The examples below use the SMB base URL. For MAX accounts, use your MAX base URL instead.** ## Step 1: Create campaign Call [POST /campaigns](https://apireference.getresponse.com/#operation/createCampaign) to create a campaign (contact list). Only `name` is required. It must be unique in your account, be 3-64 characters long, and cannot contain `/`, `\`, `@`, `[` or `]`. ```bash curl -X POST \ https://api.getresponse.com/v3/campaigns \ -H 'X-Auth-Token: api-key YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "quick_start_list" }' ``` Here’s an example of the same call from a GetResponse MAX (PL) account: ```bash curl -X POST \ https://api3.getresponse360.pl/v3/campaigns \ -H 'X-Auth-Token: api-key YOUR_API_KEY' \ -H 'X-Domain: example.com' \ -H 'Content-Type: application/json' \ -d '{ "name": "quick_start_list" }' ``` A `201 Created` response returns the full campaign resource, including its `campaignId`. Copy the `campaignId` for the next step: ```json { "campaignId": "Ls3jm", "href": "https://api.getresponse.com/v3/campaigns/Ls3jm", "name": "quick_start_list", "techName": "17e911d2d2e32f9a05d722241bdecb45", "languageCode": "PL", "isDefault": "false", "createdOn": "2024-05-14T09:12:31+0000", "confirmation": { ... }, "profile": { ... }, "postal": { ... }, "optinTypes": { "api": "double", "email": "single", "import": "single", "webform": "double" }, "subscriptionNotifications": { ... } } ``` If the name is already in use in your account, you’ll get a `409 Conflict` response with error code `1008`. Choose a different name and try again. For more information on possible errors, see [Errors](errors). ## Step 2: Retrieve campaign Call [GET /campaigns/{campaignId}](https://apireference.getresponse.com/#operation/getCampaign) with the `campaignId` returned in step 1 to confirm that the campaign exists. ```bash curl -X GET \ https://api.getresponse.com/v3/campaigns/Ls3jm \ -H 'X-Auth-Token: api-key YOUR_API_KEY' ``` A `200 OK` response with the same `campaignId` and `name` confirms your integration is working end to end. An invalid or missing API key returns `401 Unauthorized` with error code `1014`. For more information on possible errors, see [Errors](errors). ## Next steps - [Authentication](authentication) for OAuth 2.0 and GetResponse MAX headers - [Adding contacts](case-study/adding-contacts) to add a contact to the new campaign --- # GetResponse MCP Server Connect AI assistants such as Claude, Cursor, VS Code, and ChatGPT to GetResponse through the Model Context Protocol. The GetResponse MCP server lets compatible AI assistants work with your contacts, lists, newsletters, AI campaigns, and campaign statistics through standardized tools. ## How MCP works The Model Context Protocol (MCP) is a standard for connecting AI assistants to external systems. After you add the GetResponse server to an MCP-compatible client, the client discovers the available tools and can use them to complete tasks you request. The GetResponse MCP server uses Streamable HTTP and OAuth 2.0. When you connect, your client opens the GetResponse sign-in and authorization flow. You don't need to create or paste an API key. Actions run with the permissions of the GetResponse account you authorize. Review proposed changes before approving actions that create or update account data. ## Getting started 1. [Choose the MCP endpoint](mcp/endpoints) for your GetResponse account. 2. Follow the [agent setup instructions](mcp/configuration) for your MCP client. 3. Sign in to GetResponse and authorize the connection when prompted. ## Available tools ### Contacts and lists - **`get_campaigns`** — Returns the contact lists defined in your account. - **`get_custom_fields_list`** — Returns a paginated list of custom fields. - **`get_recently_added_contacts`** — Returns recently added contacts. - **`get_contacts_by_name`** — Searches for contacts by name. - **`get_contacts_by_campaign`** — Searches for contacts in a specified list. - **`get_contacts_who_received_any_message_in_last_days`** — Returns contacts who received a message during the specified number of days. - **`get_contacts_who_did_not_open_any_message_in_last_days`** — Returns contacts who didn't open a message during the specified number of days. - **`get_contacts_who_clicked_any_link_in_any_message_in_last_days`** — Returns contacts who clicked a link during the specified number of days. - **`get_contacts_who_opened_any_message_in_last_days`** — Returns contacts who opened a message during the specified number of days. - **`get_contacts_who_have_custom_field_assigned`** — Returns contacts that have a specified custom field assigned. ### Newsletters - **`get_email_addresses_list`** — Returns the email addresses available to the current user. - **`get_newsletter_content`** — Returns the content of a specified newsletter. - **`get_drafts_list`** — Returns a paginated list of newsletter drafts. - **`create_newsletter`** — Creates a newsletter. - **`update_newsletter`** — Updates an existing newsletter. - **`create_newsletter_with_content`** — Creates a newsletter with AI-generated content. ### Newsletter statistics - **`get_general_performance`** — Returns a newsletter statistics summary for the specified conditions. - **`get_broadcasts_sent_between_dates`** — Returns newsletters sent between specified dates. - **`get_single_newsletter_performance_summary`** — Returns the performance summary for a specified newsletter. ### AI campaigns - **`create_marketing_campaign`** — Creates a marketing campaign with a landing page, newsletter, and welcome message. --- # Agent setup You can connect any MCP-compatible client that supports remote Streamable HTTP servers and OAuth 2.0. The examples below use the standard GetResponse endpoint: ``` https://mcp.getresponse.com/ ``` GetResponse MAX customers must replace this URL with their account-specific [MCP endpoint](endpoints). Enter the selected URL exactly as shown, without adding `/mcp`. Authentication is handled through OAuth 2.0. After adding the server, follow the browser-based GetResponse sign-in and authorization flow opened by your client. ## Claude Custom connectors are available on Free, Pro, Max, Team, and Enterprise plans. Free accounts can add one custom connector. 1. Open **Customize > Connectors** in Claude. 2. Select the plus button, then **Add custom connector**. 3. Enter your MCP endpoint as the remote MCP server URL and select **Add**. 4. Find the GetResponse connector and select **Connect**, then sign in to GetResponse and authorize the connection. On Team and Enterprise plans, an Owner must first add the connector under **Organization settings > Connectors > Add > Custom > Web**. Organization members can then connect to it under **Customize > Connectors**. ## Claude Code Run the following command in your terminal: ```bash claude mcp add --transport http getresponse https://mcp.getresponse.com/ ``` For a GetResponse MAX account, replace `https://mcp.getresponse.com/` with your account-specific endpoint. Start Claude Code, run `/mcp`, select `getresponse`, and complete the GetResponse authorization flow. ## VS Code For a standard GetResponse account, use [one-click installation](https://vscode.dev/redirect/mcp/install?name=getresponse&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.getresponse.com%2F%22%7D). Run **MCP: Add Server** from the Command Palette, select HTTP as the server type, enter your MCP endpoint, and choose **Global** or **Workspace** as the target. You can also add the server manually to `.vscode/mcp.json`: ```json { "servers": { "getresponse": { "type": "http", "url": "https://mcp.getresponse.com/" } } } ``` For a GetResponse MAX account, replace the value of `url` with your account-specific endpoint. When VS Code first connects to the server, complete the GetResponse authorization flow in your browser. ## Cursor For a standard GetResponse account, use [one-click installation](https://cursor.com/install-mcp?name=GetResponse&config=eyJ1cmwiOiJodHRwczovL21jcC5nZXRyZXNwb25zZS5jb20vIn0%3D). Add the server to `.cursor/mcp.json` for the current project or `~/.cursor/mcp.json` to make it available globally: ```json { "mcpServers": { "getresponse": { "url": "https://mcp.getresponse.com/" } } } ``` For a GetResponse MAX account, replace the value of `url` with your account-specific endpoint. Open **Customize** in Cursor, enable the server, and complete the GetResponse authorization flow. ## ChatGPT Developer mode is available to Pro, Plus, Business, Enterprise, and Education accounts on the web. 1. Open **Settings > Security and login** and enable **Developer mode**. 2. Go to [ChatGPT Plugins](https://chatgpt.com/plugins). 3. Select the plus button and create a developer-mode app for the remote MCP server. Enter `GetResponse` as the name, use your [MCP endpoint](endpoints) as the server URL, and select OAuth authentication. 4. Sign in to GetResponse and authorize the app. After it is created, the app appears under **Drafts** in the app settings. 5. In a new conversation, open the Plus menu, select **Developer mode**, and enable the GetResponse app. The available tools are described on the [GetResponse MCP Server](../mcp) page. --- # MCP endpoints Use the endpoint that matches your GetResponse account type. | Account type | MCP endpoint | | --- | --- | | GetResponse | `https://mcp.getresponse.com/` | | GetResponse MAX | `https://.mcp.getresponse360.pl` | | GetResponse MAX | `https://.mcp.getresponse360.com` | For GetResponse MAX, ask your account manager which endpoint to use and what value should replace ``. Enter the endpoint at its root. Don't append `/mcp` or an API version path. --- # Authentication API can be accessed by authenticated users only. This means that every request must be signed with your credentials. We offer two methods of authentication: API Key and OAuth 2.0. API key is our primary method and should be used in most cases. GetResponse MAX clients have to send an ```X-Domain``` header in addition to the API key. Supported OAuth 2.0 flows are: Authorization Code, Client Credentials, Implicit, and Refresh Token. ## API key Follow these steps to send an authentication request: - Find your unique and secret API key in the panel: [https://app.getresponse.com/api](https://app.getresponse.com/api) - Add a custom ```X-Auth-Token``` header to all your requests. For example, if your API key is ```jfgs8jh4ksg93ban9Dfgh8```, the header will look like this: ``` X-Auth-Token: api-key jfgs8jh4ksg93ban9Dfgh8 ``` ::: warning For security reasons, unused API keys expire after 90 days. When that happens, you’ll need to generate a new key to use our API. ::: #### Example authenticated request ```bash $ curl -H "X-Auth-Token: api-key jfgs8jh4ksg93ban9Dfgh8" https://api.getresponse.com/v3/accounts ``` ## OAuth 2.0 To use OAuth 2.0 authentication, you need to get an "Access Token". For more information on how to obtain a token, head to our dedicated page: [OAuth 2.0](authentication/oauth2.md) To authenticate a request using an Access Token, set the value of ```Authorization``` header to "Bearer" followed by the Access Token. #### Example If the Access Token is ```jfg93baDfgh8n9Ds8jh4ksg93ban9Dfgh8``` ``` Authorization: Bearer jfg93baDfgh8n9Ds8jh4ksg93ban9Dfgh8 ``` ## GetResponse MAX GetResponse MAX customers need to take an extra step to authenticate the request. All requests have to be sent with an ```X-Domain``` header that contains the client's domain. For example: ``` X-Domain: example.com ``` Please note that the header must contain only the domain name, without the protocol identifier (```http://``` or ```https://```). ### X-Parent-Login header A user can be in one or more accounts (parent accounts). The ```X-Parent-Login``` header allows you to limit API requests to a specific parent account. For example, a user is assigned to two parent accounts with logins: ```abc@getresponse.com``` and ```xyz@getresponse.com```. If the ```X-Parent-Login: abc@getresponse.com``` header is set in API requests, they'll be made only for the parent account with the login```abc@getresponse.com```. If a request is made with the header ```X-Parent-Login: xyz@getresponse.com```, it will return information only for the parent account with the login ```xyz@getresponse.com```. --- # Oauth 2.0 ## Register your own application If you want to use an OAuth flow to authorize your application, first register your application here: You need to provide a name, short description, and redirect URL. ## Choosing grant flow Once your application is registered, you can click on it to see your client_id and client secret. They're basically a login and password for your application, so be sure not to share them with anyone. Next, decide which authentication flow (grant type) you want to use. Here are your options: - choose the Authorization Code flow if your application is server-based (you have a server with its own domain and server-side code), - choose the Implicit flow if your application is based mostly on JavaScript or client-side code, - choose the Client Credential flow if you want to test your application or access your GetResponse account, - implement the Refresh Token flow to handle token expiration if you use the Authorization Code flow. ## Authorization Code flow First, your application must redirect the resource owner to the following URL: ``` https://app.getresponse.com/oauth2_authorize.html?response_type=code&client_id=_your_client_id_&state=xyz ``` The state parameter is there for security reasons and should be a random string. When the resource owner grants your application access to the resource, we will redirect the browser to the redirect URL you specified in the application settings and attach the same state as the parameter. Comparing the state parameter value ensures that the redirect was initiated by our system. #### Example redirect with authorization code ``` https://myredirecturi.com/cb?code=ed17c498bfe343175cd7684c5b09979f2875b25c&state=xyz ``` The code parameter is an authorization code that you can exchange for an access token within 10 minutes, after which time it expires. #### Exchanging authorization code for the access token Here's an example request to exchange authorization code for the access token: ``` $ curl -u client_id:client_secret https://api.getresponse.com/v3/token \ -d "grant_type=authorization_code&code=ed17c498bfe343175cd7684c5b09979f2875b25c" ``` ::: tip Remember to replace client_id and client_secret with your OAuth application credentials. ::: #### Example response ```json { "access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35", "expires_in": 3600, "token_type": "Bearer", "scope": null, "refresh_token": "170d9f64e781aaa6b3ba036083faba71b2fc4e6c" } ``` ## Client Credentials flow This flow is suitable for development purposes, especially in cases when you need to quickly access API to create some functionality. You can get the access token with a single request: #### Request ``` $ curl -u client_id:client_secret https://api.getresponse.com/v3/token \ -d 'grant_type=client_credentials' ``` ::: tip Remember to replace client_id and client_secret with your OAuth application credentials. ::: #### Response ```json { "access_token": "e2222af2851a912470ec33c9b4de1ea3a304b7d7", "expires_in": 86400, "token_type": "Bearer", "scope": null } ``` You can also go to , click the action button for your application, and select "Credentials code". This will open a popup with a generated access token. You can then use the access token to authenticate your requests, for example: ``` $ curl -H "Authorization: Bearer e2222af2851a912470ec33c9b4de1ea3a304b7d7" https://api.getresponse.com/v3/from-fields ``` ## Implicit flow First, your application must redirect the resource owner to the following URL: ``` https://app.getresponse.com/oauth2_authorize.html?response_type=token&client_id=_your_client_id_&redirect_uri=https://myredirecturi.com/cb&state=xyz ``` When the resource owner grants your application access to the resource, we will redirect the owner to the URL that was specified in the request. There is no code exchange process because, unlike the Authorization Code flow, the redirect already has the access token in the parameters. #### Example redirect ``` https://myredirecturi.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&state=xyz&token_type=bearer&expires_in=3600 ``` ## Refresh Token flow You need to refresh your access token if you receive this error message as a response to your request: ```json { "httpStatus": 401, "code": 1014, "codeDescription": "Problem during authentication process, check headers!", "message": "The access token provided is expired", "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1014", "context": { "sentToken": "b8b1e961a7f9fd4cc710d5d955e09c15a364ab71" } } ``` If you are using the Authorization Code flow, you need to use the refresh token to issue a new access token/refresh token pair by making the following request: ``` $ curl -u client_id:client_secret https://api.getresponse.com/v3/token \ -d 'grant_type=refresh_token&refresh_token=170d9f64e781aaa6b3ba036083faba71b2fc4e6c' ``` ::: tip Remember to replace client_id and client_secret with your OAuth application credentials. ::: The response you'll get will look like this: ```json { "access_token": "890fdsa2f5d7b189fc4e6c4b1d170d9f591238ss", "expires_in": 86400, "token_type": "Bearer", "scope": null, "refresh_token": "170d9f64e781aaa6b3ba036083faba71b2fc4e6c" } ``` ## GetResponse MAX There are some differences when authenticating GetResponse MAX users: - the application must redirect to a page in the client's custom domain, for example: `https://custom-domain.getresponse360.com/oauth2_authorize.html` - token requests have to be sent to one of the GetResponse MAX APIv3 endpoints (depending on the client's environment), - token requests have to include an X-Domain header, - the application has to be registered in a GetResponse MAX account within the same environment. --- # Errors ## Error Code: **1** (Internal error) {#1} ### HTTP status Code: 500 Something went wrong on our side, and there is nothing you can do to fix that. We will get notified about all errors immediately, but if you are experiencing this often then please let us know! These errors are connected to system failures, database connection lost or DDoS attack. ## Error Code: **1000** (General error of validation process) {#1000} ### HTTP status Code: 400 This is a general validation error - usually you will see this if there is more than one type of validation error in request message. We will give you more detailed information in the 'context' part of the error response. Please look there to see what went wrong. ## Error Code: **1001** (Resource that is related to given resource cannot be found) {#1001} ### HTTP status Code: 400 Some of our resources are connected to other resources - you cannot get one without the other. If in your requests you specify ID of that related resources that will be invalid or nonexistent, then we cannot fulfill the request and response with this error code is our way to notify you about it. Common examples of this error are: * creating a new newsletter using invalid campaign * searching for valid clicktractId but using wrong autoresponder * adding contact with nonexistent custom-field ## Error Code: **1002** (Resource state forbids that kind of action) {#1002} ### HTTP status Code: 400 Whatever you tried to do, this cannot be accomplished. There are many reasons: * You tried to add contact that is already on your blacklist * You tried to add contact, but the email address is invalid (domain don't exist or domain don't have this email registered) * You tried to add contact that was previously deleted or bounced * You tried to send draft but given message is not a draft * You tried to set not active from-field as a default one We always add more information in the context or description section in the error response. ## Error Code: **1003** (Parameter has wrong format) {#1003} ### HTTP status Code: 400 This is validation error. There are many other validation types, but this particular checks if value of parameters you send in request are in proper type. Generally we check: * resource ID format * email address syntax * IP address syntax * reserved words * forbidden words * checks against dictionary (e.g. opt-in type values during adding contact) * date format * phone number format ## Error Code: **1004** (Wrong number of values for multi-value parameter (hash, table)) {#1004} ### HTTP status Code: 400 Sometimes we expect that parameters should be an array (table) with multiple values inside. There can be limits (max or min) to number of values inside that parameter, and when you see this error, you go past that limits. We will tell you what are the limits in any particular case - just take a look into 'context' section of error response. ## Error Code: **1005** (Parameter has empty value) {#1005} ### HTTP status Code: 400 We sometimes expect that some fields must have value in them, but you sent us a parameter without it. We will tell you where we expect a value - look at 'context' section in error response. ## Error Code: **1006** (Parameter has wrong type) {#1006} ### HTTP status Code: 400 Sometimes we require that some parameters have values of some type. We check mostly primitives (string, integer, boolean). We will return bad value and name of a parameter in the 'context' section of the error response. ## Error Code: **1007** (Parameter value has incorrect length) {#1007} ### HTTP status Code: 400 Some parameters have restriction on how long or short they can be. We always return in the 'context' section what is the limit in that case. ## Error Code: **1008** (There is another resource with the same value of unique property) {#1008} ### HTTP status Code: 409 We cannot add resource because there is already resource with the same unique properties. This can be: * autoresponder name * contact email in campaign * campaign name * custom-field name * goal name * goal URL * goal update when * goal profile name * search-contacts name * suppression name ## Error Code: **1009** (Resource you tried to manipulate is used somewhere and this manipulation is forbidden) {#1009} ### HTTP status Code: 400 Sometimes it is forbidden to edit some resource because it is used somewhere else. Examples: * remove custom-field when it is used on webforms * remove custom-field when it is used in search-contacts (segmentation) * remove from-field that is used * removing goal when it is used in search-contacts (segmentation) * removing goal-profile when it is used in search-contacts (segmentation) * removing newsletter when it is used in search-contacts (segmentation) * removing search-contacts (segments) when it is used as a target for sending messages ## Error Code: **1010** (Error in external resources) {#1010} ### HTTP status Code: 400 This error is related to any external checks we need to do in order to fulfill your request. If for any reason this external call fails we return this error and try to add some detailed information to 'context' section in the error response. One example could be a check during GoalProfile creation. ## Error Code: **1011** (Message is already in "sending" mode, you cannot change its properties) {#1011} ### HTTP status Code: 400 You tried to edit newsletter that is already being sent. ## Error Code: **1012** (Error during parsing message content) {#1012} ### HTTP status Code: 400 Error in the message body. We tried to analyze message body and cannot find one of mandatory merge\_word. We will try to give you more details in 'context' section in the error response. ## Error Code: **1013** (Resource with given ID cannot be found) {#1013} ### HTTP status Code: 404 There is simply no resource of given ID. ## Error Code: **1014** (Problem during authentication process) {#1014} ### HTTP status Code: 403 This error may be returned for a couple of different reasons: * Authorization headers were not sent (check headers if there is X-Auth-Token header sent during every request) * Authorization headers were ok, but there is no token (it should be passed as X-Auth-Token: token\_type your\_api\_key) * Authorization headers were ok, but token type is unknown (it should be passed as X-Auth-Token: api-key your\_api\_key) * Headers were ok, but api-key is invalid ## Error Code: **1015** (Too many request to API, quota reached) {#1015} ### HTTP status Code: 429 In terms of this error, there could be a couple of reasons you should look for: * You reached quota limit and throttling system was activated * Our monitoring system recognised your requests pattern as a potential threat and temporarily disabled access to the API. It will be enabled in next 15 minutes. Please contact us, we will check and explain what could be wrong. * Our monitoring system recognised you requests pattern as a risky behaviour and permanently disabled access to the API. Blockade could be removed only by our support. * Restrictions policy for that account forbids access from this IP address. Please contact with our support. ## Error Code: **1016** (Too many request to API or suspected behaviour, API was temporarily blocked, please wait) {#1016} ### HTTP status Code: 403 ## Error Code: **1017** (Suspected behaviour, API was permanently blocked, please contact with our support) {#1017} ### HTTP status Code: 403 ## Error Code: **1018** (Your IP was blocked) {#1018} ### HTTP status Code: 403 ## Error Code: **1019** (Service unavailable) {#1019} ### HTTP status Code: 503 The server is currently unable to handle the request due to a maintenance. ## Error Code: **1021** (There is something wrong with your request headers) {#1021} ### HTTP status Code: 400 This error is all about your request headers. In most cases you should send us at least: * X-Auth-Token - if you are using api-key authorization * Authorization - if you are using oAuth2 authorization * Content-Type - this should be sent always, and for now it should be set to 'application/json' If you get this error, please check you request headers. ## Error Code: **1023** (Access forbidden) {#1023} ### HTTP status Code: 403 The account or collaborator account you are using does not have access to permission or campaign required to perform the requested action. Please contact account owner (if you are a collaborator) for additional permissions or our support team (if you are the account owner). ## Error Code: **1024** (Domain not found) {#1024} ### HTTP status Code: 404 ## Error Code: **1027** (Failed to add contacts. Limit reached. Log in to GetResponse to check your account status) {#1027} ### HTTP status Code: 400 ## Error Code: **1028** (Resource is restricted and cannot be modified or deleted) {#1028} ### HTTP status Code: 400 ## Error Code: **1029** (Resource property is restricted and cannot be used) {#1029} ### HTTP status Code: 400 --- Limits & throttling =================== GetResponse API calls are subject to throttling to ensure a high level of service for all users. Time frame ---------- Time frame is a period of time for which we calculate the API call limits. The limits reset in every time frame. The time frame duration is **10 minutes**. Basic rate limits ----------------- Each user is allowed to make **30,000 API calls per time frame** (10 minutes) and **80 API calls per second**. Parallel requests limit ----------------------- It is possible to send up to **10 simultaneous requests**. Headers ------- Every API response includes a few additional headers: * `X-RateLimit-Limit` – the total number of requests available per time frame * `X-RateLimit-Remaining` – the number of requests left in the current time frame * `X-RateLimit-Reset` – seconds left in the current time frame Errors ------ The **429 Too Many Requests** HTTP response code indicates that the limit has been reached. The error response includes `currentLimit` and `timeToReset` fields in the context section, with the total number of requests available per time frame and seconds left in the current time frame respectively. Reaching the limit ------------------ When you reach the limit, you need to wait for the time specified in `timeToReset` field or `X-RateLimit-Reset` header before making another request. --- # API Collections To help you get started faster with the GetResponse API, we provide ready-to-use collections for the most popular API client tools: [Postman](https://www.postman.com/), [Bruno](https://www.usebruno.com/) and the JetBrains IDEs HTTP Client (`.http` files). Each collection contains a set of pre-configured requests covering the GetResponse API v3 endpoints, so you can explore and test the API without writing any code. ## Postman collection [Postman](https://www.postman.com/) is a popular API platform for building and using APIs. - [Download the Postman collection](/getresponse-postman-collection.zip) ### How to use it 1. Download and unzip the collection. 2. Open Postman and go to **Import**. 3. Select the extracted `.json` file. 4. Set up your `X-Auth-Token` (or OAuth 2.0) authentication as described in the [Authentication](authentication) section. ### Example environment The collection uses [Postman environment variables](https://learning.postman.com/docs/sending-requests/variables/managing-environments/) so you don't have to hardcode your credentials in every request. Below is an example environment file — create your own with these variables (values are anonymized, so replace them with your own data): ```json { "id": "00000000-0000-0000-0000-000000000000", "name": "GetResponse API", "values": [ { "key": "url", "value": "https://api.getresponse.com", "enabled": true }, { "key": "token", "value": "your-api-key", "enabled": true }, { "key": "domain", "value": "your-domain.com", "enabled": true } ], "_postman_variable_scope": "environment", "_postman_exported_at": "2024-01-01T00:00:00.000Z", "_postman_exported_using": "Postman/11.0.0" } ``` - `url` — the base URL of the API you want to call, e.g. `https://api.getresponse.com` (GetResponse MAX clients should use their own API domain, e.g. `https://api3.getresponse360.pl`). - `token` — your API key, used in the `X-Auth-Token` header as described in the [Authentication](authentication) section. - `domain` — required for GetResponse MAX clients only. Your account's domain, sent in the `X-Domain` header. See the [GetResponse MAX](authentication#getresponse-max) section for details. ::: tip NOTE You can import this file as a new environment in Postman (**Environments** > **Import**), or create a new environment manually and add these variables yourself. ::: ## Bruno collection [Bruno](https://www.usebruno.com/) is a fast, open-source, git-friendly API client — an alternative to Postman. - [Download the Bruno collection](/getresponse-bruno-collection.zip) ### How to use it 1. Download and unzip the collection. 2. Open Bruno and choose **Open Collection**. 3. Select the extracted collection folder. 4. Set up your `X-Auth-Token` (or OAuth 2.0) authentication as described in the [Authentication](authentication) section. ### Example environment Bruno also uses environments to store variables like your API key, so you don't have to hardcode them in every request. The same `url`, `token` and `domain` variables described in the [Postman example environment](#example-environment) above apply here as well — only the way you set them up is different: 1. Open the collection in Bruno. 2. In the top-right corner, open the environment selector and choose **Configure**. 3. Create a new environment (or select an existing one bundled with the collection) and add the `url`, `token` and `domain` variables with your own values. 4. Save the environment and select it from the environment selector so it's used for your requests. ## HTTP Client collection The [HTTP Client](https://www.jetbrains.com/help/phpstorm/http-client-in-product-code-editor.html) is a tool built into JetBrains IDEs (e.g. PhpStorm, IntelliJ IDEA) that lets you create, edit and run HTTP requests directly from `.http` files, without leaving the IDE. - [Download the HTTP Client collection](/http.zip) ### How to use it 1. Download and unzip the collection. 2. Open the extracted `http` folder in your JetBrains IDE. 3. Open any `.http` file - each one corresponds to a group of requests (e.g. `Contacts.http`, `Campaigns (Lists).http`). 4. Set up your API key as described below, then select the `dev` environment from the dropdown available in the `.http` file editor before running a request. ### Example environment The collection comes with two environment files: - `http-client.env.json` - contains the public `baseUrl` variable. - `http-client.private.env.json` - contains the `token` variable (your API key). Open `http-client.private.env.json` and replace the `YOUR_API_KEY_HERE` value with your real API key, as described in the [Authentication](authentication) section. This file should not be shared or committed with a real key. ::: tip NOTE Some requests use path variables, e.g. `{{contactId}}`, `{{campaignId}}`, etc. Their values are not predefined in the environment - at the top of each `.http` file that uses them, there is a declaration such as `@campaignId = {your campaignId id}`. Replace the value after the `=` sign with your own ID so requests in that file can use it. ::: ::: tip NOTE All collections are updated occasionally and might not include the newest endpoints. ::: --- # Dynamic Content Dynamic content lets you create personalized messages with custom content, like links, dates, or recipients' details. **Note:** Dynamic content requires coding skills. Talk to a developer if you haven't used a programming language before. Requirements ------------ Dynamic Content is a programing language, and so it requires strict syntax: * There can be only one instruction per tag. * The syntax is case-sensitive. Use upper case and lower case as shown in the examples under specific sections. * In HTML messages, backticks can be used instead of double quotes. * A message may be composed of 1024 parts, where each block of text or a dynamic content tag counts as one part. Support ------- Our dynamic content is created and maintained by the **GetResponse DevZone Team**. [Contact us](https://www.getresponse.com/features/support) if you find any errors or have problems using dynamic content. We're here to help. --- # Campaign ## Campaign predefined values Merge-words that are constant in your campaign. ```{{PREDEFINED `my_shop_name`}}``` [Prettifiers](prettifiers.md) are allowed. Predefined values can be defined on [GetResponse WWW](https://app.getresponse.com/campaigns_predefined_variables.html). Empty string is inserted into the message on undefined value. ## Campaign or contact or message info Basic merge-words providing info about campaign, contact or message. Please note that "contact" is called a "subscriber" in tokens due to backward compatibility. ```md {{CONTACT `subscriber_name`}} ``` Supported tokens: * `subscriber_name` * `subscriber_first_name` – Everything up to first space. * `subscriber_last_name` – Empty if name doesn’t consist of two parts separated by space. * `subscriber_email` * `subscriber_ip` * `subscriber_origin` * `campaign_name` – Refers to message's campaign * `campaign_description` – Refers to message's campaign * `campaign_from_name` – Refers to message's campaign * `campaign_from_email` – Refers to message's campaign * `campaign_reply_to_email` – Refers to message's campaign * `campaign_link_protocol` – Refers to message's campaign * `campaign_link_domain` – Refers to message's campaign * `message_from_name` * `message_from_email` * `message_reply_to_email` * `campaign_id` * `message_id` * `subscriber_id` * `message_name` – Empty in subscription confirmation messages Prettifiers are allowed. Empty string is inserted into the message on undefined value. This behavior can be changed by providing default value. ```md {{CONTACT `subscriber_name` `My friend`}} ``` ::: tip Tokens `campaign_id`, `message_id`, and `subscriber_id` return the same `IDs` as in API. For example you can pass `subscriber_id` token in [links](links.md): ::: ```md {{LINK `http://myshop.com/index.html?visitor={{CONTACT `subscriber_id`}}`}} ``` After receiving click on your server use this `ID` to get additional info about visitor from API using [getContactById](https://apireference.getresponse.com/#operation/getContactById). --- # Conditions Allows to display various parts of message depending on **campaign or contact or message\_info**, **contact custom fields or tags**, **contact geo location** or **dates**. ```md {{IF `(pet IS_DEFINED)`}} {{IF `(pet STRING_EQ 'dog')`}} Buy a bone for your dog! {{LINK `http://mysite.com/shop/product/bone_for_dog`}} {{ELSIF `(pet STRING_EQ 'cat')`}} Buy a mouse toy for your cat! {{LINK `http://mysite.com/shop/product/toy_mouse_for_cat`}} {{ELSE}} You may find something for your pet in my store! {{ENDIF}} {{ELSE}} You don't have a pet yet. Buy one! {{ENDIF}} {{IF `((city STRING_EQI 'Gdańsk') LOGIC_OR ((city STRING_EQI 'Gdynia') LOGIC_OR (city STRING_EQI 'Sopot')))`}} You can visit our store located in 3City in person! {{ELSE}} Go to our online page: {{LINK `http://mysite.com/shop`}} {{ENDIF}} {{IF `(day_name STRING_NEQ 'Sunday')`}} We're open today. {{ELSE}} Please visit us from Monday to Saturday {{ENDIF}} ``` Order of tags: * ```{{IF `...`}}``` – Mandatory beginning of conditional statement. * ```{{ELSIF `...`}}``` – Optional block, multiple allowed. * ```{{ELSE}}``` – Optional default block, one allowed. * ```{{ENDIF}}``` – Mandatory closing of conditional statement. Building conditions step by step: * Take left operand, this can be name of **contact custom field or tag** or token from **campaign or contact or message\_info**, **contact geo location**, **dates**. ```md DAY ``` * Lowercase this operand. ```md day ``` * Take right operand which is constant value you like left operand to be compared against. ```md 8 ``` * Quote this operand in single quotes, this is mandatory even if operand is numeric. ```md '8' ``` * Join operands with operator. ```md day NUMBER_GT '8' ``` * Wrap this pair in round brackets to get conditional statement. ```md (day NUMBER_GT '8') ``` * (optional) If you need more complex logic you can join conditional statements with logic operator. Remember about top round brackets to create conditional statement. ```md ((day NUMBER_GT '8') LOGIC_AND (day NUMBER_LT '16')) ``` * Use conditional statement in tag param. ```md {{IF `((day NUMBER_GT '8') LOGIC_AND (day NUMBER_LT '16'))`}} You will see this if message was sent between 8th and 16th day of month. {{ENDIF}} ``` Operators: * `NUMBER_LT` – Less than. * `NUMBER_GT` – Greater than. * `NUMBER_EQ` – Equal. * `NUMBER_NEQ` – Not equal. * `NUMBER_GEQ` – Greater or equal. * `NUMBER_LEQ` – Less or equal. * `NUMBER_DIV` - True if divisable by given value. * `STRING_EQ` – Equal. * `STRING_EQI` – Equal but case-insensitive. * `STRING_NEQ` – Not equal. * `STRING_NEQI` – Not equal case-insensitive. * `STRING_CO` – Contains. * `STRING_COI` – Contains but case-insensitive. * `STRING_NCO` – Not contains. * `STRING_NCOI` – Not contains case-insensitive. * `DATE_IS_ANNIVERSARY` - True during anniversary of operand (check notes below for details). Only left operand is required - `(subscriber_created_at DATE_IS_ANNIVERSARY)`. * `DATE_IS_MENSIVERSARY` - True during mensiversary of operand. Only left operand is required - `(revewal_started_at DATE_IS_MENSIVERSARY)`. * `LOGIC_OR` – Union used if A and B are conditions. * `LOGIC_AND` – Intersection used if A and B are conditions. * `IS_DEFINED` – Check for value presence. Only left operand is required - `(car IS_DEFINED)`. * `NOT_DEFINED` – Check for value absence. Only left operand is required - `(car NOT_DEFINED)`. ::: warning If you use `(pet STRING_EQ 'dog')` and contact custom field pet is not defined then the statement will evaluate to false. In most cases this is what you mean, but it is better to use additional `IS_DEFINED` operator to keep logic clean. ::: ::: warning If you apply `NUMBER_*` operator to not numeric value it will evaluate to false. ::: ::: warning If custom field in condition is multi value then conditional statement will evaluate to true if any element matches it. So if custom pet has values "mouse" and "hamster" then `(pet STRING_EQ 'mouse')` is true because "mouse" value meets the condition, but also `(pet STRING_NEQ 'mouse')` is true because "hamster" value meets the condition. ::: ## Mangling Mangling allows you to use **contact custom field name or tag name or token name** as left operand without having to worry about its tag type. For example if you use `(city STRING_EQI 'Gdańsk')` then: 1. Value of contact custom field city is checked. If it exists conditional statement is resolved to true or false at this stage. 2. City is also token in contact geo location. If it exists and conditional statement is not yet resolved then conditional statement is resolved to true or false at this stage. 3. Conditional statement is false if not yet resolved. Presence of custom/tags of given name is always checked before presence of such named token in other tags. Do not nest whole tags, for example  ```{{IF `{{CUSTOM `pet`}} STRING_EQ 'dog'`}}``` is not correct syntax. ## Anniversary/mensiversary notes * **Month length differences**: If day in operand does not exist in current month anniversary / mensiversary happens on last day of current month. For example someone who subscribed on `2026-01-31` has mensiversary on `2026-04-30` (April does not have 31 days). Someone who subscribed on `2024-02-29` (leap year) has anniversary / mensiversary on `2026-02-28` (February in non-leap year does not have 29 days). * **Time zones**: GeoIP time zone is used if known. Otherwise user timezone set in GetResponse account is used. For example someone from Poland who subscribed at `2024-01-21 10:00:00 UTC` with known GeoIP of `Europe/Warsaw` (so subscription time from his perspective is `2024-01-21 11:00:00 Europe/Warsaw`) has example mensiversary on `2024-02-21 Europe/Warsaw` (`2024-01-20 23:00:00` - `2024-01-21 23:00:00` UTC). So feature respects calendar day boundaries from recipient perspective. **Warning**: Custom field values do not carry time zone information and are assumed to be in UTC for this conversion. Do not store custom field values recalculated to your local time or double conversion will happen. --- # Contact ## Contact custom fields Merge-words for contact custom (additional) fields. ```md {{CUSTOM `car`}} ``` [Prettifiers](http://apidocs.getresponse.com/v3/dynamic-content/prettifiers) are allowed. Contact custom fields can be defined on [GetResponse WWW](https://app.getresponse.com/custom_fields_list.html "GetResponse WWW") or by GetResponse API. Empty string is inserted into the message on undefined value. This behavior can be changed by providing default value. ```md {{CUSTOM `car` `your car`}} ``` Contact tags ------------ Merge-words for contact tags. ```md {{TAG `responsive`}} ``` Tags can be defined by [GetResponse API](../resources/tags.md). Empty string is inserted into the message on undefined value. This merge-word is especially useful in [conditions](conditions.md). Contact geo location -------------------- Geo location info based on contact IP (if available). ```md {{GEO `country`}} ``` Supported tokens: * `latitude` * `longitude` * `country_code` * `country` * `city` * `region` * `postal_code` * `dma_code` * `continent_code` * `time_zone` - Given as name, not as offset. For example "Europe/Warsaw". [Prettifiers](http://apidocs.getresponse.com/v3/dynamic-content/prettifiers) are allowed. Empty string is inserted into the message on undefined value. This behavior can be changed by providing default value. ```md {{GEO `city` `Your city`}} ``` Contact subscription date ------------------------- Contact subscription date that can be presented in various formats. ```md {{ADDED_ON `you subscribed on DAY_ORDINATED of MONTH_NAME, it was DAY_NAME`}} ``` (will insert "you subscribed on 11th of July, it was Friday") Format part can contain special tokens (uppercased!) that will be replaced with date parts. * `CENTURY` – For example "21". * `YEAR` – For example "2012". * `YEAR_SHORT` – For example "10". * `MONTH` – From "01" to "12". * `MONTH_NAME` – From "January" to "December". * `MONTH_NAME_SHORT` – From "Jan" to "Dec". * `DAY` – From "01" to "31". * `DAY_NAME` – From "Monday" to "Sunday". * `DAY_NAME_SHORT` – From "Mon" to "Sun". * `HOUR` – From "00" to "23". * `MINUTE` – From "00" to "59". * `SECOND` – From "00" to "59". Format can also contain every other character except double quotes and back-tick to format date. ::: tip You can get rid of leading zeroes by suffixing numeric token with `_NONZERO`. ::: * `HOUR_NONZERO` – From "0" to "23". ::: tip You can ordinate numeric token value by suffixing it with `_ORDINATED`. ::: * `DAY_ORDINATED` – From "1st", "2nd", "3rd" to "31st". Ordinated values are always stripped of leading zeros. ::: warning You cannot use `_NONZERO` or `_ORDINATED` with naming tokens like `DAY_NAME`. ::: ::: tip Date is presented in contact time zone. If it is not known then user time zone is used. ::: --- # Dates ## Dates Date of email delivery that can be presented in various formats and be time-shifted. ```md {{DATE `this email was sent on DAY_ORDINATED of MONTH_NAME, it was DAY_NAME`}} ``` (will insert "this email was sent on 11th of July, it was Friday") Format part can contain special tokens (uppercased!) that will be replaced with date parts. * `CENTURY` – For example "21". * `YEAR` – For example "2012". * `YEAR_SHORT` – For example "10". * `MONTH` – From "01" to "12". * `MONTH_NAME` – From "January" to "December". * `MONTH_NAME_SHORT` – From "Jan" to "Dec". * `DAY` – From "01" to "31". * `DAY_NAME` – From "Monday" to "Sunday". * `DAY_NAME_SHORT` – From "Mon" to "Sun". * `HOUR` – From "00" to "23". * `MINUTE` – From "00" to "59". * `SECOND` – From "00" to "59". Format can also contain every other character except double quotes and back-tick to format date. ::: tip You can get rid of leading zeroes by suffixing numeric token with `_NONZERO`. ::: * `HOUR_NONZERO` – From "0" to "23". ::: tip You can ordinate numeric token value by suffixing it with `_ORDINATED`. ::: * `DAY_ORDINATED` – From "1st", "2nd", "3rd" to "31st". Ordinated values are always stripped of leading zeros. ::: warning You cannot use `_NONZERO` or `_ORDINATED` with naming tokens like `DAY_NAME`. ::: ::: tip Date supports time-shift. ::: ```md {{DATE `YEAR-MONTH-DAY` `+10 DAY`}} ``` Offset must be given as "+" or "-" sign, value of time shift and unit of time shift. Allowed units are. * `YEAR`(`S`) – 365 days. * `MONTH`(`S`) – 30 days. * `DAY`(`S`) * `HOUR`(`S`) Total amount of time shift cannot exceed +/-16 years. If it does then unmodified date will be inserted into a message. ::: tip Date is presented in contact time zone. If it is not known then user time zone is used. ::: ## Timers ::: warning **This function is deprecated and will be removed on 2021-05-01.** ::: Countdown to/since given timestamp or contact subscription date. ```md {{TIMER `2012-12-21 00:00:00` `DAYS_UNIT HOURS_UNIT to the end of the world` `World ended DAYS days ago`}} ``` (will insert "291 days 7 hours to the end of the world" at the moment this doc was created and will insert "World ended 32 days ago" when it is 32 days after the timestamp date) ```md {{TIMER `added_on` `` `You signed up DAYS_UNIT ago`}} ``` (will insert "You signed up 35 days ago") First param is timestamp that can be provided as: * Date and time - "YYYY-MM-DD HH:MM:SS" - must be in UTC time zone. * Date - "YYYY-MM-DD" - must be in UTC time zone. * Contact subscription date - "added\_on" Second / third params (both are mandatory, even if empty) are future / past formats. They are displayed if the message was sent before / after given timestamp. Those formats can contain special tokens that will be replaces with amounts of those units. * `CENTURIES` * `YEARS` - 365 days. * `MONTHS` – 30 days. * `DAYS` * `HOURS` * `MINUTES` * `SECONDS` ::: tip If you want unit name along with numeric value suffix token with `_UNIT`, for example: ::: ```md {{TIMER `2010-01-01 00:00:00` `HOURS_UNIT` ``}} ``` (will insert "8 hours") ::: tip Tokens are greedy. It means that you do not have to use all of them in formats. Tokens you use can "consume" amount of time in a smart way. ::: ```md {{TIMER `2010-01-01 00:00:00` `HOURS_UNIT` ``}} ``` (will insert "49 hours") ```md {{TIMER `2001-01-01 00:00:00` `DAYS_UNIT and HOURS_UNIT` ``}} ``` (will insert "2 days and 1 hour" because `DAYS` token "consumed" 48 hours) --- # External Content ::: warning External Content and External Lexpad are complementary features but they serve very different purposes. Please read **both** documentations very carefully and then choose the right solution for your task. Otherwise you may fall into inefficient design antipatterns that will affect sending speed and may generate excessive network traffic. You should use **External Content** when you want to **include paragraphs that depend on some limited set of variables**. ::: ## Synopsis Let's assume you have real estate business and you want to present "offer of the day" in your messages. Of course you want to avoid editing your messages on daily basis and you want to personalize this offer for contacts. To do so include following tag in your message: ```md {{EXTERNAL `http://example.com/index.html?location={{GEO `city`}}&type={{CUSTOM `interested_in`}}&`}} ``` When message is sent: 1. Link is evaluated. For example contact is from `"city"` Chicago and you stored his preferences in multivalue custom `"interested_in"`, then target link will be `http://example.com/index.html?location=Chicago&type=condominiums,duplexes&`. 2. External content is downloaded from this link. Your server should return content correlated with passed params. 3. Content in placed in message instead of tag. And each of your contact will automatically get offer of the day matching their location and interests. ## General rules * Your server must respond within 4 seconds. * Your server must be capable of handling up to 100 concurrent requests. * Response cannot be larger than 64KB per one tag. * Returned content must be UTF-8 encoded. * Returned content must have valid Dynamic Content syntax. **If any of rules above are broken then message will be sent to contact, but  evaluated URL will be inserted into the message in place of EXTERNAL tag.** ## Don't! * Use External Content unique per contact. For example by using ```{{CONTACT `subscriber_id`}}``` tag as link parameter or some customs that are unique per contact (like phone number). This will be painfully slow. If you want to do so then you probably need [External Lexpad](external-lexpad.md). * Format data structures on your side. For example if you want to return "top 20 real estate offers in your location" then you probably need [External Lexpad](external-lexpad.md). * Return whole www pages from your server (with headers, CSS styles, scripts, and so on). This probably will not work because of broken message structure and limited capabilities of email clients. Your server should only return piece of content that you want in this part of message. As much formatting as possible should remain in static message content. **If we notice high ratio of different URLs compared to amount of sent messages (content is very contact-specific) or inefficient flow we may block this feature until those issues are resolved.** ## Advanced stuff ### Link params External Content URL can be parametrized link with [campaign predefined values](campaign.md), [contact custom field](contact.md), [campaign or contact or message info](campaign.md) or [contact geo location](contact.md) tags inside URL. Just nest corresponding tags in your external link. Nested tags have following restrictions: * Can not contain default value - ```{{CONTACT `subscriber_name` `Friend`}}``` is forbidden. * Can not use [prettifiers](prettifiers.md) - ```{{CONTACT `uc(subscriber_name)`}}``` is forbidden. * Are encoded in UTF-8 as URL param, so if ```{{CONTACT `subscriber_name`}}``` is `"Pabian Paweł"` it will be inserted into link as `"Pabian%20Pawe%C5%82"` to make link valid. Please note that `"/"` character will also be encoded as `"%2F"` so do not use nested tag as part of your link path. ### Nested tags You can use every Dynamic Content tag in content returned from your server. For external ```{{EXTERNAL `http://example.com/about_us` }}``` your server can return ```md Hi {{CONTACT `ucfw(subscriber_first_name)`}}! We are international company. {{LINK `http://company.com`}} ``` This response will be re-evaluated (including click tracking), so following content will be inserted into the message. ```md Hi Paweł! We are international company. http://getresponse.com/click.html?x=a62a&.. ``` ### Multiple externals You can include many external tags in single message. ```md Hi This is what you may need for your pet {{EXTERNAL `http://pet.store.com/?animal={{CUSTOM `pet`}}&limit=1`}} And you may check our other products {{EXTERNAL `http://pet.store.com/general_offer`}} ``` ### Reentrance Yes, it is possible to use External Content inside another External Content. Moreover, sometimes it is recommended to achieve better message structure and reduce network traffic. For example: ```md {{EXTERNAL `http://example.com/product?id=123`}} ``` May return: ```md Hammer drill Neighborex-2000XT Buy now and you will get bonus: {{EXTERNAL `http://example.com/product?id=456`}} ``` Where inner external may return: ` Set of 30 cemented carbide drills. Diameters: 32mm, 30mm, 25mm, ... ` This way you won't have to resend the same bonus product content over and over again with each base product purchased. And if inner product is used frequently it will benefit from content caching (see below). ### Caching Fetched content is cached per URL basis. And this cache will be reused every time the same URL is spotted, even if it is in different message. That allows to reduce network traffic, but may be tricky if you updated returned content under given URL and want it to be fetched again before new message is sent. To force refresh you can add dummy param and ignore it on the server side.: ```md {{EXTERNAL `http://example.com/greeting?message={{CONTACT `message_id`}}`}} ``` This way URL will be different in every message and cache will not be used. ### Content types Be aware of message content type. If you send dual (plain and HTML) messages your external content source should also be able to return plain and HTML. For example use in plain part of the message ```{{EXTERNAL `http://about.me/main?type=plain"}}``` and in HTML part of the message use ```{{EXTERNAL `http://about.me/main?type=html`}}``` and serve different content from your server depending on type param value. ### Authorization If you want to prevent reading external content from other places than GetResponse you can use additional param that will be passed as `X-Auth-Token` header in HTTP request. ```md {{EXTERNAL `https://example.com/secret_stuff` `400aad99cd7f1191451adb226ba40349`}} ``` Token will be as safe as message content itself (so for example don't use external with authorization inside external without it) and transmission between GetResponse and your server (use HTTPS). --- # External Lexpad ::: warning External Content and External Lexpad are complementary features but they serve very different purposes. Please read **both** documentations very carefully and then choose the right solution for your task. Otherwise you may fall into inefficient design antipatterns that will affect sending speed and may generate excessive network traffic. You should use **External Lexpad** when you want to **populate message content using complex data structures that are specific for every recipient**. ::: ## Availability Currently this feature is only available for messages defined through [API](https://apireference.getresponse.com) (excluding RSSes). To use it provide `sendSettings` → `externalLexpad` section in API call such as [createNewsletter](https://apireference.getresponse.com/#operation/createNewsletter). ## Synopsis Let's assume that you have online book store. Every customer in this store: * Has corresponding contact in GetResponse (for example you synchronize them using [API](https://apireference.getresponse.com)). * Can choose favorite book categories. Now you want to send message to your contacts containing section with new books in their categories. At this point you should notice few things: * You will apply the same formatting for many elements (books) in array. * Every element (book) will have many attributes (author, title, cover type, tags, and so on). * Set of those elements (books) will be quite unique for every customer. For example if there are 16 categories in your store then there are 65536 sets of favorite categories possible. That is the sign, that you should use **External Lexpad**, not External Content ### WebService First you have to provide endpoint, that will return data structure with new books for every GR contact. Let's assume it is located at: `https://example.com/new_books.json` Communication in both ways uses JSON and your service will get following **POST** request: ```json { "campaign": { "id": "ABC123" }, "message": { "id": "QWE123" }, "subscriber": { "id": "RTY456" } } ``` IDs in query are the same as returned by [API](https://apireference.getresponse.com). Please note that "contact" is called a "subscriber" in request due to backward compatibility. The authorization token that you've passed in API call will be sent back in `X-Auth-Token` header and **must be checked by your endpoint**. Now your webservice should find corresponding customer in book store, check which categories are marked by this customer as favorite, find list of new books in those categories and return them in JSON data structure of your choice: ```json { "month": "May", "new_books": { "Science-fiction": [ { "title": "Attack from Mars", "author": "John Foo" }, { "title": "Robots", "author": "Anna Bar" } ], "Horror": [ { "title": "Dark forest", "author": "Peter Baz" } ] } } ``` This structure is called "Lexpad" and serves the same purpose as lexpads in programming languages - provides data for code execution. ### Message Message content can use special mergewords that allows to iterate over provided data structure. ```md Hi {{CONTACT `subscriber_first_name`}} Check out new books released in {{TOPIC `month`}} that may interest you: {{LOOP `new_books` `category` `books`}} In category {{TOPIC `category`}} we have {{LOOP `books` `book`}} - {{TOPIC `book` `title`}} written by {{TOPIC `book` `author`}} {{ENDLOOP}} {{ENDLOOP}} Happy reading! ``` ### Result Before message is sent to subscriber GetResponse will send Lexpad request to your webservice and will use received data to execute mergeword logic, producing following message: ```md Hi Tom Check out new books released in May that may interest you: In category Science-fiction we have - Attack from Mars written by John Foo - Robots written by Anna Bar In category Horror we have - Dark forest written by Peter Baz Happy reading! ``` As you can see External Lexpad feature allows to use more sophisticated template logic. And while most Dynamic Content tags operate on data stored in GetResponse (for example contact name) for `LOOP` tags you provide data yourself through your webservice. Simple? OK, let's dig into details :) General rules ------------- * WebService must respond within 4 seconds. * Response cannot be larger than 32KB. * Lexpad must be in JSON format using UTF-8 character set. * Top level structure must be JSON object. Arrays or bare values are not allowed. **If any of rules above are broken then message won't be sent to contact**. * It is strictly forbidden to use any formatting directives in Lexpad. Values within must never contain any HTML tags, CSS styles, newlines, etc. Whole formatting must be done on message content level exclusively to speed up sending process and minimize lexpad size and network traffic. It may be tempting to return whole piece of text preformated on webservice side without learning those `LOOP` and `TOPIC` constructs, but any detected attempt to do so will result in **immediate block of this feature**. Preformatting on server side would mean pushing over network the same formatting directives again and again, which is very inefficient and therefore we do not allow it. * It is strictly forbidden to clicktrack links personalized in LexPad per subscriber. This causes separate clicktrack entries per every link and will immediaterly clog message statistics. See "Clicktracking" section for more details. * It is recommended to return JSON in compact form, without pretty formatting. * We do not enforce how data structure inside top JSON object should look like. Dynamic Content mergeword execution is fast. Like **really, really, really fast**. So if your data has deep strucure by its nature do not be afraid to use many levels of nested `LOOP`s to format the output. TOPIC tag --------- This tag prints value available in current scope under given name (first param). It understands Scalars, Arrays and Hashes. Lexpad: ```json { "greeting": "Hello", "subject": [ "Dog", "World", "Kitty" ], "punctuation": { "dot": ".", "exclamation": "!", "question": "?" } } ``` Message: ```md {{TOPIC `greeting`}} {{TOPIC `subject` `1`}} {{TOPIC `punctuation` `exclamation`}} ``` Result: `Hello World !` Explanation: * First param is value name. * Second param is not present for Scalar values, it is numeric for Array values and it is string for Hash values. * Accessing value in a way which do not corresponds with its type will not print such value. For example ```{{TOPIC `greeting` `foo`}}``` will be skipped because value under ``greeting`` key is a Scalar, not a Hash. The same applies to ```{{TOPIC `subject`}}```, which is an Array and expects index to be given. * Arrays are enumerated from `0`. Index is numeric but still must be quoted like any other param according to general Dynamic Content rules. * Arrays can only be indexed in positive, integer, ASCII-only numbers. There are no tricks like counting backwards using negative index, known from some programming languages. * It is impossible to use numbers as hash keys. * You can not traverse into nested lexpad ```{ `foo` : { `bar` : { `baz` : 123 } } }``` using single mergeword like ```{{TOPIC `foo` `bar` `baz`}}```. To access deeper values `LOOP` must be used. LOOP tag -------- This tag iterates over Hash and Array structures and binds values to new names. ### Iterating over Array Lexpad: ```json { "cars" : [ `Dodge`, `Uaz`, `Fiat` ] } ``` Message: ```md {{LOOP `cars` `car`}} {{TOPIC `car`}} {{ENDLOOP}} ``` Result: ```md Dodge Uaz Fiat ``` Explanation: * First param is value name. * Value is expected to be an Array. Otherwise whole `LOOP` will be skipped. * Second param describes new name that values within Array will be bound to. This `"car"` name will be available for `TOPIC`s, `IF`s or nested `LOOP`s within this `LOOP` scope (continue reading to encounter those mythical creatures). ### Iterating over Hash Lexpad: ```json { "sounds": { "cat": "meow", "pig": "oink", "dog": "woof" } } ``` Message: ```md {{LOOP `sounds` `pet` `does`}} {{TOPIC `pet`}} - {{TOPIC `does`}} {{ENDLOOP}} ``` Result: ```md cat - meow dog - woof pig - oink ``` Explanation: * First param is value name. * Value is expected to be a Hash. Otherwise whole `LOOP` will be skipped. * Second and third param describe new key and value name that values within Hash will be bound to. Those values are available for `TOPIC`s, `IF`s or nested `LOOP`s within this `LOOP` scope. * Hashes are unordered by nature, therefore order from your JSON file will not be preserved. Iteration will go over keys sorted lexicographically. Advanced stuff -------------- Let's assume you have diet business and you are sending daily diet for each contact. We'll use the same lexpad for next few cases: Lexpad: ```json { "diet": { "Breakfast": { "Eggs": { "preparation": "boiled", "amount": "2", "nutrition": { "fat": "25g", "proteins": "26g", "carbs": "4g" }, "recipe": "https://example.com/boiled_eggs.html" } }, "Dinner": { "Beef": { "preparation": "grilled", "amount": "100g", "nutrition": { "proteins": "30g", "fat": "10g" }, "recipe": "https://example.com/grilled_burger.html" }, "Potatoes": { "preparation": "boiled", "amount": "100g", "nutrition": { "proteins": "2g", "fat": "1g", "carbs": "20g" }, "recipe": "https://example.com/boiled_potatoes.html" } } } } ``` ### Nested iteration It was already shown in Synopsis, but now let's go through the details: ```md {{LOOP `diet` `meal` `ingredients`}} ... {{ENDLOOP}} ``` This will bind keys in `"diet"` Hash to `"meal"` name. So `"meal"` will be `"Breakfest"` and "`Dinner"`. Values in `"diet"` hash will be bound to `"ingredients"` name and they contain Hash. So to display every ingredient in every meal you have to iterate over `"ingredients"`. ```md {{LOOP `diet` `meal` `ingredients`}} {{LOOP `ingredients` `ingredient_name` `ingredient_attributes`}} ... {{ENDLOOP}} {{ENDLOOP}} ``` You can go as deeply as needed, just be aware of data type (Hash or Array) you are iterating on. ### Binding scopes Now that we have base iteration let's print something useful: ```md {{LOOP `diet` `meal` `ingredients`}} For {{TOPIC `meal`}} prepare: {{LOOP `ingredients` `ingredient_name` `ingredient_attributes`}} - {{TOPIC `ingredient_attributes` `amount`}} {{TOPIC `ingredient_attributes` `preparation`}} {{TOPIC `ingredient_name`}} Enjoy {{TOPIC `meal`}}! {{ENDLOOP}} {{ENDLOOP}} ``` Which will print: ```md For Breakfast prepare: - 2 boiled Eggs Enjoy Breakfast! For Dinner prepare: - 100g grilled Beef - 100g boiled Potatoes Enjoy Dinner! ``` In this example you can see, that: * `TOPIC` behaves exactly the same way, doesn't matter how deep in `LOOP` structures it is burried. If `"ingredient_attributes"` in inner most loop is a Hash then you can get value under `"amount"` key by using ```{{TOPIC `ingredient_attributes` `amount`}}```. * Each name assigned in `LOOP` is also available in sub`LOOP`s. That's why it is possible to use ```Enjoy {{TOPIC `meal}}``` in inner most loop, while `"meal"` was bound in outer loop. ### Re-binding scopes You can rebind name in inner LOOP. ```md {{LOOP `diet` `name` `ingredients`}} {{LOOP `ingredients` `name` `attributes`}} {{ENDLOOP}} {{ENDLOOP}} ``` Try to **avoid it** unless you know what you are doing. In this case for example you won't be able to use ```Enjoy {{TOPIC `name`}}``` part, because ingredient name in inner `LOOP` scope masks meal name from outer `LOOP`. ### Clicktracking Any value reachable through `TOPIC` tag can be used as URL in `LINK` tag. ```md {{LOOP `diet` `meal` `ingredients`}} {{TOPIC `meal`}}: {{LOOP `ingredients` `ingredient` `ingredient_attributes`}} - {{TOPIC `ingredient`}} Recipe {{LINK `ingredient_attributes` `recipe`}} {{ENDLOOP}} {{ENDLOOP}} ``` This will print: ```md Breakfast: - Eggs Recipe http://getresponse.com/click.html?... Dinner: - Beef Recipe http://getresponse.com/click.html?... - Potatoes Recipe http://getresponse.com/click.html?... ``` And all those links will be visible under message statistics. Explanation: * Way of accessing values is exactly the same as for `TOPIC` tag. First param is value name. Second param is not present for Scalar values, it is numeric for Array values and it is string for Hash values. * You cannot give custom names to links clicktracked from Lexpad, second param is used exclusively for Lexpad indexing. Limitations: * Length of clicktracked link is limited to 2048 characters. * Clictracking does not interpret Dynamic Content inside link, it is not possible to provide through LexPad links like ```http://example.com?email={{CONTACT `subscriber_email`}}```. * Links must not be unique per subscriber. Due to limitation described above it may be tempting to compose links per subscriber like `http://example.com?email=foo@example.com` and pass them in LexPad. However it will cause multiple subscriber-specific links appear in message statistics, each one will be clicktracked individually for single subscriber. This will severly impact statistics performance and is not allowed. ### Conditions Any Scalar value reachable through `TOPIC` tag can be used as left value in `IF` tag. ```md {{LOOP `diet` `meal` `ingredients`}} {{TOPIC `meal`}}: {{IF `(meal STRING_EQ 'Dinner')`}} Eat before 17:00 {{ENDIF}} {{LOOP `ingredients` `ingredient` `ingredient_attributes`}} - {{TOPIC `ingredient_attributes` `preparation`}} {{TOPIC `ingredient`}} {{LOOP `ingredient_attributes` `ingredient_attribute_name` `ingredient_attribute_value`}} {{IF `((ingredient_attribute_name STRING_EQ 'preparation') LOGIC_AND (ingredient_attribute_value STRING_EQ 'grilled'))`}} Don't burn it! {{ENDIF}} {{ENDLOOP}} {{ENDLOOP}} {{ENDLOOP}} ``` This will print: ```md Breakfast: - boiled Eggs Dinner: Eat before 17:00 - grilled Beef Don't burn it! - boiled Potatoes ``` Explanation: * Left side of condition is value name and it always mean Scalar reference. More on that later. * Lexpad has precedence over custom values - ```{{IF `(car ...)`}}``` will take value from Lexpad first and fallback to value from custom if Lexpad one is not present. Use distinctive names for your Lexpad keys to avoid confusion! One shortcoming that you've probably noticed is that `IF` works only on Scalar values and cannot reach into Hashes or Arrays like `TOPIC` can. So `"meal"` is Scalar value, accessible in this scope through ```{{TOPIC `meal`}}``` and also usable in condition directly through ```{{IF `(meal ...)`}}```. However making condition on `"preparation"` method is slightly more complicated. It can be easilly printed by ```{{TOPIC `ingredient_attributes` `preparation`}}``` but condition cannot use the same syntax and left value must be bound as Scalar. You have to make another `LOOP`, inside which `"ingredient_attribute_name"` and `"ingredient_attribute_value"` will be Scalars. Then you should filter out keys which you are not interested in using `(ingredient_attribute_name STRING_EQ 'preparation')` portion of the `IF` and then compare value in `"ingredient_attribute_value"`. If you run into this issue then the best way out is to rethink Lexpad layout and provide data in more direct or de-normalized way. --- # Links ## Clicktracked links Mark links for click counting tracking and assign optional description for statistics. ```md {{LINK `http://mysite.com`}} ``` For messages composed on [GetResponse WWW](https://app.getresponse.com/choose_html_or_plain.html?msg_type=broadcast "GetResponse WWW") editor all links are marked for tracking automatically and tracking takes place if "Track click-through's of your links" on editor window is chosen. For messages sent using GetResponse API links must be wrapped in `{{LINK}}` tag on clients side to mark it for tracking. Also `"flag" : [ "clicktrack" ]` must be passed to method. ::: warning Tracking is not the same as wrapping links in HTML tags. To make tracked link clickable in HTML you still need to use anchor. ::: ```md My site ``` Note that you can use back-ticks instead of double quotes and remove white spaces to avoid trouble with HTML editors. ::: tip You can use campaign predefined values, campaign or contact or message_info, contact custom fields or contact geo location tags inside your URL. ::: ```md {{LINK `http://mysite.com/login?email={{CONTACT `subscriber_email`}}&from_where={{GEO `city`}}`}} ``` Nested tags have following restrictions: * Can not contain default value - ```{{CONTACT `subscriber_name` `Friend`}}``` is forbidden. * Can not use prettifiers - ```{{CONTACT `uc(subscriber_name)`}}``` is forbidden. * Are encoded in UTF-8 as as URL param, so if ```{{CONTACT `subscriber_name`}}``` is "Pabian Paweł" it will be inserted into link as "Pabian%20Pawe%C5%82" to make link valid. Please note that "/" character will also be encoded as "%2F" so do not use nested tag as part of your link path. * You cannot create nested date tag in links. ::: tip You can give links a custom description. ::: ```md {{LINK `http://mysite.com` `My site`}} ``` If description is given link is shown under this name instead of URL on performance stats. It makes stats easier to read and allows to do two tricks – splitting and merging. Splitting allows to show many links with the same URL under different names. It may be useful for statistical purposes like creating a "click heat map" of your message. ```md Hello {{LINK `http://mysite.com` `My page at the beginning of the message`}} Some message body {{LINK `http://mysite.com` `My page at the end of the message`}} Sincerely ``` Now you know which link was clicked more often because - despite common URL - those links will be shown under separate names on performance stats. Merging is opposite to splitting – many links with different URLs will be shown under one name on performance stats. This is helpful if you do not need to distinguish them. ```md {{LINK `http://mysite.com/shop/main` `Main shop page`}} {{LINK `http://myoldsite.com/redirect/shop` `Main shop page`}} ``` System links ------------ Links that allow contact to perform actions. ```md {{LINK `me`}} ``` Supported tokens and message types they can be used in: * `me` (newsletter, autoresponder, rss) – Manage subscription and details. This is the same link as in footer. * `change_details` (newsletter, autoresponder, rss) – Manage contact details. This is the same link as in footer. * `unsubscribe` (newsletter, autoresponder, rss) – Unsubscribe link. This is the same link as in footer. * `view` (newsletter, autoresponder, rss) – View message on website. May be useful if contact is using email client that blocks content, for example images. * `confirm` (confirmation) - Confirm subscription in double optin mode. Social links ------------ Links that allow contact to share info about message on social media. ```md {{LINK `social_digg`}} ``` Allowed tokens: * `social_digg` * `social_facebook` * `social_googleplus` * `social_linkedin` * `social_myspace` * `social_twitter` ::: warning If you want your newsletter to be shared on social media you must select "Publish in RSS" on last step of creating newsletter process in old editor. ::: --- # Prettifiers Several functions are allowed in some tags: * `lc()` – Lowercase all characters. `ComPUTer` will be inserted into message as `computer`. * `uc()` – Uppercase all characters. `coMPuTEr` will be inserted into message as `COMPUTER`. * `ucfw()` – Uppercase first letters in each word and lowercase other. `o'reilly bOOk PUBLISHING` will be inserted into message as `O'Reilly Book Publishing`. Note that this beautifulizer also recognizes parts that should not be uppercased. `Ludwig VAN beethoven Jr` will be inserted as `Ludwig van Beethoven jr`. Current list of exceptions consists of: von, van, bin, ibn, mgr, dr, prof, imc, jr and may be extended if needed. * `ucfs()` – Uppercase first letter of every sentence and lowercase other letters. `how ARE you? i'm FINE.` will be inserted into message as `How are you? I'm fine.`. * `md5()`, `sha1()`, `sha256()` - Calculate hash function from given value. * `escape_html()` - You should always use this one if you print subscriber data (like custom or name) directly in HTML messages to avoid accidental HTML breaks and XSS injections. * `escape_url_param()` - Useful when you need to use some data as URL param to avoid breaking URL structure. You should NOT use it if URL is inside LINK tag because then values are escaped automatically. For polish users declensions are available for names. * `vocative()` – Create vocative form of name, Tomek will be inserted into message as Tomku. Currently Polish language is supported. Prettifiers can be nested. For example if ```md {{CONTACT `subscriber_first_name`}} ``` inserts `paweł` then ```md {{CONTACT `ucfw(vocative(subscriber_first_name))`}} ``` will insert `Pawle`. Prettifiers are multi-value aware. For example if ```md {{CUSTOM `car`}} ``` inserts `honda, toyota, dodge` then ```md {{CUSTOM `ucfw(car)`}} ``` will insert `Honda, Toyota, Dodge`. --- # Randoms Inserts random text from provided list. ```md {{RANDOM `Hi` `Hello` `Hey`}} ``` --- # Callbacks Callbacks allow external systems to be notified about GetResponse contact activities. ## Configuration Callbacks can be managed using API [GET /accounts/callbacks](https://apireference.getresponse.com/#operation/getCallbacks), [POST /accounts/callbacks](https://apireference.getresponse.com/#operation/updateCallbacks) and [DELETE /accounts/callbacks](https://apireference.getresponse.com/#operation/disableCallbacks) methods or on [web interface](https://app.getresponse.com/callback). We support SSL, so you can use either HTTP or HTTPS for callback messages. ## Parameters Sample HTTP callback looks like this: ```http request http://foo.bar/callback?action=open \ &ACCOUNT_ID=A1&account_login=myaccount \ &CAMPAIGN_ID=C1&campaign_name=mycampaign \ &MESSAGE_ID=M1&message_name=My%20message&message_subject=Some%20subject \ &CONTACT_ID=C1&contact_name=Friend&contact_email=friend@implix.com ``` All ```*_ID``` params are compatible with corresponding identifiers in API. So for example after receiving [open](./callbacks/open) callback one may call `get_message` API method with `MESSAGE_ID` from callback to fetch additional information about opened message. Those params are case-sensitive. ## Failures Callback timeout is 4 seconds, callbacks that are not received **are lost and will not be repeated**. Make sure that the target server is capable of handling the expected amount of requests, especially when SSL URL is given which is more CPU-intensive. ## Support The GetResponse Callback interface is created and maintained by the _GetResponse DevZone_ Team. If you run into an error or you have difficulty using Callbacks please contact us using [this form](http://www.getresponse.com/feedback.html?devzone=yes) and we will provide all the support we can, in order to solve your problems. --- # Click ## Click _Params:_ - ```action``` - Always ```click```. - ```ACCOUNT_ID``` - ```account_login``` - ```CAMPAIGN_ID``` - ```campaign_name``` - ```MESSAGE_ID``` - ```message_name``` - ```message_subject``` - ```LINK_ID``` - ```link_url``` - ```CONTACT_ID``` - ```contact_name``` (optional) - ```contact_email``` --- # Goal ## Goal _Params:_ - ```action``` - Always ```goal```. - ```ACCOUNT_ID``` - ```account_login``` - ```CAMPAIGN_ID``` - ```campaign_name``` - ```GOAL_ID``` - ```goal_profile``` - ```goal_domain``` - ```goal_name``` - ```goal_url``` - ```CONTACT_ID``` - ```contact_name (optional)``` - ```contact_email``` - ```goal_param_0``` - ```goal_param_1 (optional)``` - ```goal_param_2 (optional)``` - ```goal_param_3 (optional)``` - ```goal_param_4 (optional)``` - ```goal_param_5 (optional)``` --- # Open ## Open _Params:_ - ```action``` - Always ```open```. - ```ACCOUNT_ID``` - ```account_login``` - ```CAMPAIGN_ID``` - ```campaign_name``` - ```MESSAGE_ID``` - ```message_name``` - ```message_subject``` - ```CONTACT_ID``` - ```contact_name``` (optional) - ```contact_email``` --- # Subscribe ## Subscribe _Params:_ - ```action``` - Always ```subscribe```. - ```ACCOUNT_ID``` - ```account_login``` - ```CAMPAIGN_ID``` - ```campaign_name``` - ```CONTACT_ID``` - ```contact_name``` (optional) - ```contact_email``` - ```contact_ip``` (optional) - In case of double-optin this is the IP than confirmation link was clicked from. - ```contact_origin``` - One of ```import```, ```email```, ```www```, ```panel```, ```leads```, ```sale```, ```api```, ```forward```, ```survey```, ```iphone```, ```copy```, ```landing_page```. --- # Survey ## Survey _Params:_ - ```action``` - Always ```survey```. - ```ACCOUNT_ID``` - ```account_login``` - ```CAMPAIGN_ID``` - ```campaign_name``` - ```MESSAGE_ID``` (optional) - Present if survey was sent in email message. - ```message_name``` (optional) - Present if survey was sent in email message. - ```message_subject``` (optional) - Present if survey was sent in email message. - ```SURVEY_ID``` - ```survey_name``` - ```survey_title``` (optional) - ```QUESTION_ID``` - ```question_name``` - ```question_answer``` (optional) - Present if question is of text type. - ```OPTION_ID``` (optional) - Present if question has predetermined options to select. - ```option_name``` (optional) - Present if question has predetermined options to select. - ```CONTACT_ID``` (optional) - Present if survey was sent in email message. - ```contact_name``` (optional) - Present if survey was sent in email message. - ```contact_email``` (optional) - Present if survey was sent in email message. ::: tip Every answer generates a separate callback. So if you have a survey with one text question, one question with a single select answer and one question with three, multi select answers you may receive up to 5 callbacks for one contact filling out this survey. It also means that the survey does not have to be completed by a contact to generate callbacks. ::: --- # Unsubscribe ## Unsubscribe _Params:_ - ```action``` - Always ```unsubscribe```. - ```ACCOUNT_ID``` - ```account_login``` - ```CAMPAIGN_ID``` - ```campaign_name``` - ```CONTACT_ID``` - ```contact_name``` Field deprecated (always null). Presence only for backwards compatibility purpose. - ```contact_email``` ::: warning This callback is generated only when a contact uses the unsubscribe link. Other removal reasons such as bounces or complaints are not reported through this callback. ::: --- # Webhooks ## Introduction Webhooks let you send real-time data from GetResponse to any other platform you're using. You can get notified about contact-related events, including subscribes, unsubscribes, and link clicks. [View all webhook events](#webhooks-events) To create a webhook in your GetResponse account, go to [Webhooks](https://app.getresponse.com/webhooks/create) and click **Create webhook**. Then, pick the event and provide your webhook URL. ## Endpoint specification Here are a few things to keep in mind when setting up and working with webhooks: 1. Your endpoint needs to be able to process HTTPS requests. So, your app needs to use HTTPS. Make sure your server has a valid SSL certificate configured and installed. 2. Your endpoint must allow requests from the available [IP addresses](https://us-ms.gr-cdn.com/ip-ranges.json). Any restrictions, such as a firewall, will prevent proper communication. 3. Your endpoint must process the request within **5 seconds**. If we don't receive a response, the webhook will timeout, and the connection will close. 4. To confirm a webhook is received, your endpoint should return one of the following 2xx HTTP status codes: - `200 OK` - `201 Created` - `202 Accepted` - `204 No Content` 5. The response body must contain JSON: `{"status": "OK"}` Without it, the request will be retried despite a 2xx status code. ::: warning Webhooks will not work properly if the endpoint is not configured according to our endpoint specification. ::: ## Authentication To verify a webhook request comes from GetResponse, you can add your own query string parameter at the end of your webhook URL. This will allow you to accept only the requests containing the parameter. Your URL may look like this: `https://www.example-webhook-url.com/?secret=xyz` ::: tip NOTE The parameter value and the name can be anything you want. ::: ## Retry policy If the webhook request fails because of a network or server issue, we will retry 3 more times at increasing intervals. ### Requests that are retried We retry requests for the following reasons: - `2xx (if there's no required response body)` - `429 (Too Many Requests )` - `all 5xx` - `Timeout (no response received within 5 seconds)` ### Requests that are NOT retried We don't retry requests if your endpoint returns any for the following status codes: - `1xx` - `3xx (redirects)` - `4xx (except 429)` ## Webhook batching By default, each event is sent as an individual request, but you can merge many events into a single request. This process is known as batching. If you expect to receive many events from your GetResponse account, we recommend you batch them to improve the performance of your integration. ### Batch specification - The batch size can vary, but the maximum is 100 events per batch. - Depending on your webhook configuration and event volume, different types of webhooks can end up grouped in the same batch without any problem. - The payload of batched webhooks is an array filled with objects representing events. - Event objects have the typical webhook payload structure. [Learn more](payloads) #### Payload example ```json [ { "type": "contact_opened_message", "contact": { "contactId": "abc123", "email": "example@example.com", "name": "Friend", "campaign": { "campaignId": "bcd234", "name": "my_first_campaign", "href": "https://api.getresponse.com/v3/campaigns/bcd234" }, "href": "https://api.getresponse.com/v3/contacts/abc123" }, "message": { "resourceType": "autoresponders", "resourceId": "cde345", "name": "my_first_newsletter", "subject": "My First Newsletter", "href": "https://api.getresponse.com/v3/autoresponders/cde345" }, "account": { "accountId": "def456" }, "event": { "occurredAt": "2021-04-27T12:56:00+00:00" } }, { "type": "contact_clicked_message_link", "contact": { "contactId": "abc123", "email": "example@example.com", "name": "Friend", "campaign": { "campaignId": "bcd234", "name": "my_first_campaign", "href": "https://api.getresponse.com/v3/campaigns/bcd234" }, "href": "https://api.getresponse.com/v3/contacts/abc123" }, "message": { "resourceType": "autoresponders", "resourceId": "cde345", "name": "my_first_newsletter", "subject": "My First Newsletter", "href": "https://api.getresponse.com/v3/autoresponders/cde345" }, "clickTrack": { "clickTrackId": "xyz789", "name": "Some link", "url": "http://example.com", "href": "https://api.getresponse.com/v3/click-tracks/xyz789" }, "account": { "accountId": "def456" }, "event": { "occurredAt": "2021-04-27T12:56:00+00:00" } } ] ``` ### How to batch webhooks 1. Log into your GetResponse account and select **Webhooks** from the **Tools** menu. 1. Create a new webhook or start editing an existing one. 1. If creating a new webhook, change the webhook status to **Active**. 1. Under **Webhook batching**, switch the toggle button to **On**. 1. Save your changes. ## Webhooks events You can configure your webhooks to send information about the following events: - [Message opened](payloads#message-opened) - get notified **every time** a contact opens an email - [Link clicked](payloads#link-clicked) - get notified **every time** a contact clicks a link in an email - [SMS link clicked](payloads#sms-link-clicked) - get notified **every time** a contact clicks a link in a text message (SMS) - [Contact subscribed](payloads#contact-subcribed) - get notified when a contact is added. This event is **not** triggered by imports - [Contact copied](payloads#contact-copied) - get notified when a contact is copied - [Contact moved](payloads#contact-moved) - get notified when a contact is moved - [Contact unsubscribed](payloads#contact-unsubscribed) - get notified when a contact unsubscribed via unsubscribe link in an email - [Contact bounce removed](payloads#bounced-contact-removed) - get notified when a contact is removed because of bounce. - [Custom field value changed](payloads#custom-field-value-changed) - get notified whenever an **existing** contact has a custom field assigned, unassigned, or updated. ::: tip Note Updates via marketing automation and contact imports do not trigger this webhook. It's also not triggered when new contacts with custom fields are added using any method. ::: - [Contact's email changed](payloads#contact-s-email-changed) - get notified when a contact's email address has changed - [Import finished](payloads#contact-import-finished) - receive a notification when a contact import is complete, and receive information about the status (success/failure) of the import. - [Contact rejected](payloads#contact-rejected) - get notified when a contact is rejected. This event is **not** triggered by imports - [Custom report file status changed](payloads#custom_reports_file_status_changed) - get notified when a custom report is ready for download or in case an error occurs during report generation. There are only two file statuses the webhook is triggered by: `[ready, error]`. [View Webhook payload details](payloads) --- # Webhook payloads ## All webhooks share the following: - All webhooks provide data in a JSON format - All webhooks are sent using the HTTP ```POST``` method - All ```href``` properties link to resource details in [GetResponse APIv3](https://apireference.getresponse.com/) - All IDs can be used with [GetResponse APIv3](https://apireference.getresponse.com/) - Each payload contains the following fields: - ```type``` - event type - ```account``` - information **about** the account - ```event``` - information about the event ## Webhook headers Each request will have the following headers: ## Webhook types ### Message opened Get notified **every time** a contact opens an email --- ### Link clicked Get notified **every time** a contact clicks a link in an email --- ### SMS link clicked Get notified **every time** a contact clicks a link in a text message (SMS) --- ### Contact subscribed Get notified when a contact is added. This event is **NOT** triggered by imports. --- ### Contact copied Get notified when a contact is copied. --- ### Contact moved Get notified when a contact is moved. --- ### Contact unsubscribed Get notified whenever a contact unsubscribes via unsubscribe link --- ### Bounced contact removed Get notified when a bounced contact is removed from your list. --- ### Custom field value changed Get notified whenever an **existing** contact has a custom field assigned, unassigned, or updated. Please remember that the webhook is not triggered by: - Assigning a custom field when adding a new contact via any method. - Updating custom fields values via contact imports. - Updating custom field values via marketing automation. --- #### Case study 1. The multivalue custom field "pets" is assigned to a contact. The initial state of the custom field is: ["rabbit", "hamster"] - A webhook with the following values will be triggered: ``` "action": "added", "addedValues": ["rabbit", "hamster"], "removedValues": [] ``` 2. Your contact has changed the value for the custom field “pets”. The value "rabbit" is removed and two new values are provided: "cat" and "dog". - A webhook with the following values will be triggered: ``` "action": "changed", "addedValues": ["cat", "dog"], "removedValues": ["rabbit"] ``` 3. Your contact has removed the custom field "pets". - A webhook is triggered **without** custom field values. It looks as follows: ``` "action": "removed", "addedValues": [], "removedValues": [] ``` --- ### Contact's email changed Get notified when a contact's email address has changed. --- ### Contact import finished Receive a notification when a contact import is complete, and receive information about the status (success/failure) of the import. --- ### Contact rejected Get notified when a contact is rejected. This event is **NOT** triggered by imports. --- ### Custom report's file status changed Get notified when a custom report file is ready for download or in case an error occurs during report generation. --- # Case Study (how to start - examples) ## Prerequisite * This examples will use basic curl commands * I will ommit most of repeative parts of curl commands (only explain them once) * Examples are designed for SMB users not Getresponse360 ## Curl ```bash curl -H "X-Auth-Token: api-key 5377d45b66c6dd2540c3887e957fe999" https://api.getresponse.com/v3/accounts ``` * -H is a flag that allows to send Header with request. I use it to send my api-key. It is mandatory header for EVERY request. * Second parameter is a request URL. * For post request you must use flag -d with content of a post body after that. * For delete request you must use -X DELETE flag. * In next examples i will omit -H “X-Auth-Token” header ## Basic actions ### Update you account information I want to update my profile info. First let me see how this profile resource looks like… ```bash curl https://api.getresponse.com/v3/accounts ``` Response ```json { "accountId": "aJYH", "firstName": "John", "lastName": "Smith", "email": "john.smith@example.com", "phone": "+485835148754", "companyName": "LoveMyHardware", "state": "Pomorskie", "city": "Gdansk", "zipCode": "80-300", "countryCode": { "countryCodeId": "175" }, "industryTag": { "industryTagId": null }, "numberOfEmployees": "500", "timeFormat": "24h", "href": "http://api.getresponse.com/v3/account/aJYH" } ``` Hmm, it looks ok, but i want to change my phone ### Update postal information ```bash curl https://api.getresponse.com/v3/accounts -d ' { "phone": "+485865430923", } ' ``` Ok, that's done, now i need to add some nice from-fields for my emails. ### Add from-fields First I want to look at existing from-fields. ```bash curl https://api.getresponse.com/v3/from-fields ``` Response ```json [ { "fromFieldId": "ufIK", "email": "john.smith@example.com", "name": "John Smith", "isActive": "true", "isDefault": "true", "createdOn": "2014-06-16T09:07:09+0000", "activatedOn": null, "href": "http://api.getresponse.com/v3/from-fields/ufIK" } ] ``` Ok, I want to sends email to my future subscribers using the same email address but different “name” to appear in “from” field :). I decided to create two, one for PC users and one for Mac’s. #### Mac ```bash curl http://api.getresponse.com/v3/from-fields -d ' { "email": "john.smith@example.com", "name": "John 'ILoveMac' Smith" } ' ``` #### PC ```bash curl http://api.getresponse.com/v3/from-fields -d ' { "email": "john.smith@example.com", "name": "John 'ILovePC' Smith" } ' ``` I’ve created my new from-fields waited for confirmation emails and when the arrive, I’ve confirmed them and now they are active. ### Add custom-fields Ok, now it’s time for some custom fields. I want to “categorize” my subscribers based on some property I’ve defined. I have some ideas what to do with them later… #### ComputerType ```bash curl http://api.getresponse.com/v3/custom-fields -d ' { "name": "OperatingSystem", "type": "radio", "hidden": "false", "values": [ "Win", "OsX", "Linux" ] } ' ``` #### OperatingSystem ```bash curl http://api.getresponse.com/v3/custom-fields -d ' { "name": "OperatingSystem", "type": "radio", "hidden": "false", "values": [ "Win", "OsX", "Linux" ] } ' ``` #### VipStatus Last but not least I want to set certain subscribers as a “VIP”. This will be manual process, and i don’t want to subscribers changes this custom-field. This should be hidden. ```bash curl http://api.getresponse.com/v3/custom-fields -d ' { "name": "VipStatus", "type": "radio", "hidden": "true", "values": [ "Yes", "No" ] } ' ``` Now my custom-field list looks like that: ```json [ { "customFieldId": "JK", "href": "http://api.getresponse.new/v3/custom-fields/JK", "name": "ComputerType", "type": "radio", "hidden": "false", "values": [ "Mac", "PC" ] }, { "customFieldId": "eN", "href": "http://api.getresponse.new/v3/custom-fields/eN", "name": "OperatingSystem", "type": "radio", "hidden": "false", "values": [ "Linux", "OsX", "Win" ] }, { "customFieldId": "SP", "href": "http://api.getresponse.new/v3/custom-fields/SP", "name": "VipStatus", "type": "radio", "hidden": "true", "values": [ "No", "Yes" ] } ] ``` --- # Adding multiple contacts You can add contacts via the [POST /contacts/batch](https://apireference.getresponse.com/#operation/createBatchContacts) method. ## Campaign ID In GetResponse, you add contacts to a specific campaign (list). To do this, first obtain the campaign (list) ID. There are two ways to find the API-compatible campaign (list) ID: * By looking it up in the **List settings** in your account * Through the API. **Find the campaign (list) ID in List settings** 1. Log into your account. 2. Click **Contacts** or use this [shortcut](https://app.getresponse.com/lists) to display your contact lists. 3. Scroll to find the list. 4. Click the **Actions** icon (vertical ellipsis) and select **Settings**. 5. In the **General** tab, you can find the LIST TOKEN value under the **List name** field. **Find the campaign ID through the API** 1. Call the [GET /campaigns](https://apireference.getresponse.com/#operation/getCampaignList) method. 2. Find the target campaign within the JSON response. API-compatible campaign IDs are returned in the `campaignId` fields. ## Custom fields Custom fields allow you to add and store any additional information about your contacts. In the API, each custom field has a unique identifier. To retrieve the list of your custom fields, you need to call the [GET /custom-fields](https://apireference.getresponse.com/#operation/getCustomFieldList) method. A response might look like this: ```json [ { "customFieldId": "y8jnp", "href": "https://api.getresponse.com/v3/custom-fields/y8jnp", "name": "age", "fieldType": "single_select", "valueType": "string", "type": "single_select", "hidden": "false", "values": [ "18-29", "30-44", "45-59", "60+", "<18" ] }, { "customFieldId": "z9Kgt", "href": "https://api.getresponse.com/v3/custom-fields/z9Kgt", "name": "city", "fieldType": "text", "valueType": "string", "type": "text", "hidden": "false", "values": [] } ] ``` This response includes 2 custom fields: age (field ID `y8jnp`) and city (field ID `z9Kgt`). ## Tags Tags allow you to label contacts based on information you have about them. For example, they can help you organize contacts into "VIP customer" and "first-time buyer". In the API, each tag has a unique identifier. To retrieve the list of your tags, you need to call the [GET /tags](https://apireference.getresponse.com/#operation/getTagsList "https://apireference.getresponse.com/#operation/getTagsList") method. A response might look like this: ```json [ { "tagId": "bRGx8", "name": "first-time buyer", "href": "https://apireference.getresponse.com/v3/tags/bRGx8", "color": "", "createdAt": "2023-08-02T09:32:31+0000" }, { "tagId": "PxMnD", "name": "VIP customer", "href": "https://apireference.getresponse.com/v3/tags/PxMnD", "color": "", "createdAt": "2021-12-16T12:40:46+0000" } ] ``` ## Adding a contact Use the [POST /contacts/batch](https://apireference.getresponse.com/#operation/createBatchContacts) method to add contacts. Remember that all methods accept and return JSON data only. ### Basic JSON payload For the following example, let’s use the campaign ID `p86zQ`: ```json { "campaignId": "p86zQ", "contacts": [ { "name": "John Example", "email": "example@example.com" }, { "name": "John MoreExample", "email": "moreexample@example.com" } ] } ``` A request with the above payload will create a new contacts in the campaign `p86zQ`. The contacts will not be added to an autoresponder cycle, will not have any custom fields set, will not be geolocated.. ### Complete JSON payload The following is an example using all fields: ```json { "campaignId": "p86zQ", "email": "example@example.com", "contacts": [ { "name": "John Example", "email": "example@example.com", "customFieldValues": [ { "customFieldId": "y8jnp", "value": ["18-29"] }, { "customFieldId": "z9Kgt", "value": ["Podunk"] } ], "tags": { "ids": ["bRGx8", "PxMnD"] }, "dayOfCycle": 0, "scoring": 1, "ipAddress": "192.168.0.1" }, { "name": "John MoreExample", "email": "moreexample@example.com" } ] } ``` The first new contact will: * Have name set to `John Example` * Have email set to `example@example.com` * Be added to the autoresponder cycle on day 0 * Contact score set to 1 * Be added to the campaign `p86zQ` * Have two custom fields: * age, set to `18-29` * city, set to `Podunk` * Have the IP address `192.168.0.1`, which will be used to geolocate the contact. * Have two tags: * first-time buyer * VIP customer The second new contact will: * Have name set to `John MoreExample` * Have email set to `moreexample@example.com` All new contacts must have an email address. All other fields are optional. Additionally, different contacts can have fields assigned to them. For example, you can add 100 contacts with tags and 100 with custom fields. ### Response and processing If the request is successful, the API returns the HTTP code 202 Accepted. This means that the contacts has been preliminarily validated and added to the queue. It may take a few minutes to process the queue and add the contacts to the list. If your contacts didn't appear on the list, there's a possibility that it was rejected at a later stage of processing. #### Double opt-in If your list is set to use double opt-in, a contact has to click a link in a confirmation message to be added to your list. Unconfirmed contacts are not returned by the API and can be found using [Search Contacts](https://apireference.getresponse.com/#tag/Search-Contacts) only. ### Batch API Throttling Batch API is subject to special limits and throttling. You can make 80 calls per time frame (10 minutes) and only 1 call per second. The allowed batch size is 1000 contacts. ### Errors #### Error response Let’s consider this example error: ```json { "httpStatus": 400, "code": 1000, "codeDescription": "General error of validation process, more details should be in context section", "message": "Custom field invalid", "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1000", "context": [ "Empty value. ID: y8jnp" ], "uuid": "5a42dd48-7f57-4919-9b32-391e594ce375" } ``` Take note of the following fields: * `codeDescription` - general error code description * `message` - error message * `moreInfo` - link to our API Docs with additional information about error details * `context` - field and/or value that caused the problem, additional error details, etc. #### Common errors **General validation error - HTTP 400 - Code 1000** Request data is invalid. Detailed information about the error is provided in the `context` field. **Related resource not found - HTTP 400 - Code 1001** Make sure that the campaign ID and custom field or tag IDs are correct. **Resource state forbids that kind of action - HTTP 400 - Code 1002** Please refer to the context section in the error response for a detailed explanation. Reasons may include: * Contact is blacklisted in the campaign, account, or global blacklist. * Email address is invalid - the domain does not exist or user cannot be found. * Contact has been deleted or bounced. **Parameter has wrong format - HTTP 400 - Code 1003** Make sure that all values are properly formatted. Pay special attention to `value` in `customFieldValues` - it has to be an array, even if you want to set only one value. **Required field empty - HTTP 400 - Code 1005** Only two fields are required when adding a new contact - `email` and `campaignId` (nested in `campaign`). Make sure to set both of them. **Another resource with the same value of unique property - HTTP 409 - Code 1008** A given email address can only be added once to a campaign. You can, however, still add the same contact to _different_ campaigns. #### Common mistakes **Numeric campaign ID** For the `campaignId` value, use the alphanumeric TOKEN provided under the campaign name in [Campaign List](https://app.getresponse.com/lists). DO NOT use the 8-digit campaign number. **Custom field name in `customFieldValues`** `customFieldId` has to contain the custom field ID returned by [GET /custom-fields](https://apireference.getresponse.com/#operation/getCustomFieldList). DO NOT use the custom field name. **`cycle_day` field** The correct field name for adding a contact to a specific day in an autoresponder cycle is `dayOfCycle`. The API uses a lenient approach against unknown fields in requests, so using `cycle_day` will not produce an error. Instead, the field will be ignored and the contact will not be added to the autoresponder cycle. --- # Adding contacts You can add contacts via the [POST /contacts](https://apireference.getresponse.com/#operation/createContact) method. ## Campaign ID In GetResponse, you add contacts to a specific campaign (list). To do this, first obtain the campaign (list) ID. There are two ways to find the API-compatible campaign (list) ID: * By looking it up in the **List settings** in your account * Through the API. **Find the campaign (list) ID in List settings** 1. Log into your account. 2. Click **Contacts** or use this [shortcut](https://app.getresponse.com/lists) to display your contact lists. 3. Scroll to find the list. 4. Click the **Actions** icon (vertical elipsis) and select **Settings**. 5. In the **General** tab, you can find the LIST TOKEN value under the **List name** field. **Find the campaign ID through the API** 1. Call the [GET /campaigns](https://apireference.getresponse.com/#operation/getCampaignList) method. 2. Find the target campaign within the JSON response. API-compatible campaign IDs are returned in the `campaignId` fields. ## Custom fields Custom fields allow you to add and store any additional information about your contacts. In the API, each custom field has a unique identifier. To retrieve the list of your custom fields, you need to call the [GET /custom-fields](https://apireference.getresponse.com/#operation/getCustomFieldList) method. A response might look like this: ```json [ { "customFieldId": "y8jnp", "href": "https://api.getresponse.com/v3/custom-fields/y8jnp", "name": "age", "fieldType": "single_select", "valueType": "string", "type": "single_select", "hidden": "false", "values": [ "18-29", "30-44", "45-59", "60+", "<18" ] }, { "customFieldId": "z9Kgt", "href": "https://api.getresponse.com/v3/custom-fields/z9Kgt", "name": "city", "fieldType": "text", "valueType": "string", "type": "text", "hidden": "false", "values": [] } ] ``` This response includes 2 custom fields: age (field ID `y8jnp`) and city (field ID `z9Kgt`). ## Adding a contact Use the [POST /contacts](http://apidocs.getresponse.com/v3/resources/contacts#contacts.create) method to add contacts. Remember that all methods accept and return JSON data only. ### Basic JSON payload For the following example, let’s use the campaign ID `p86zQ`: ```json { "email": "example@example.com", "campaign": { "campaignId": "p86zQ" } } ``` A request with the above payload will create a new contact in the campaign `p86zQ` and set the contact’s email to `example@example.com`. The contact will not be added to an autoresponder cycle, will not have any custom fields set, will not be geolocated, and will receive the default name: “Friend”. ### Complete JSON payload The following is an example using all fields: ```json { "name": "John Smith", "email": "example@example.com", "dayOfCycle": "0", "campaign": { "campaignId": "p86zQ" }, "tags": ["y8inp", "y8inq"], "customFieldValues": [ { "customFieldId": "y8jnp", "value": ["18-29"] }, { "customFieldId": "z9Kgt", "value": ["Podunk"] } ], "ipAddress": "192.168.0.1" } ``` The new contact will: * Have name set to `John Smith` * Have email set to `example@example.com` * Be added to the autoresponder cycle on day 0 * Be added to the campaign `p86zQ` * Have two custom fields: * age, set to `18-29` * city, set to `Podunk` * Have the IP address `192.168.0.1`, which will be used to geolocate the contact. ### Response and processing If the request is successful, the API returns the HTTP code 202 Accepted. This means that the contact has been preliminarily validated and added to the queue. It may take a few minutes to process the queue and add the contact to the list. If your contact didn't appear on the list, there's a possibility that it was rejected at a later stage of processing. #### Double opt-in If your list is set to double opt-in, a contact has to click a link in a confirmation message to be added to your list. Unconfirmed contacts are not returned by the API and can be found using [Search Contacts](https://apireference.getresponse.com/#tag/Search-Contacts) only. ### Errors #### Error response Let’s consider this example error: ```json { "httpStatus": 400, "code": 1000, "codeDescription": "General error of validation process, more details should be in context section", "message": "Custom field invalid", "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1000", "context": [ "Empty value. ID: y8jnp" ], "uuid": "5a42dd48-7f57-4919-9b32-391e594ce375" } ``` Take note of the following fields: * `codeDescription` - general error code description * `message` - error message * `moreInfo` - link to our API Docs with additional information about error details * `context` - field and/or value that caused the problem, additional error details, etc. #### Common errors **General validation error - HTTP 400 - Code 1000** Request data is invalid. Detailed information about the error is provided in the `context` field. **Related resource not found - HTTP 400 - Code 1001** Make sure that the campaign ID and custom field IDs are correct. **Resource state forbids that kind of action - HTTP 400 - Code 1002** Please refer to the context section in the error response for a detailed explanation. Reasons may include: * Contact is blacklisted in the campaign, account, or global blacklist. * Email address is invalid - the domain does not exist or user cannot be found. * Contact has been deleted or bounced. **Parameter has wrong format - HTTP 400 - Code 1003** Make sure that all values are properly formatted. Pay special attention to `value` in `customFieldValues` - it has to be an array, even if you want to set only one value. **Required field empty - HTTP 400 - Code 1005** Only two fields are required when adding a new contact - `email` and `campaignId` (nested in `campaign`). Make sure to set both of them. **Another resource with the same value of unique property - HTTP 409 - Code 1008** A given email address can only be added once to a campaign. You can, however, still add the same contact to _different_ campaigns. #### Common mistakes **Numeric campaign ID** For the `campaignId` value, use the alphanumeric TOKEN provided under the campaign name in [Campaign List](https://app.getresponse.com/lists). DO NOT use the 8-digit campaign number. **Custom field name in `customFieldValues`** `customFieldId` has to contain the custom field ID returned by [GET /custom-fields](https://apireference.getresponse.com/#operation/getCustomFieldList). DO NOT use the custom field name. **`cycle_day` field** The correct field name for adding a contact to a specific day in an autoresponder cycle is `dayOfCycle`. The API uses a lenient approach against unknown fields in requests, so using `cycle_day` will not produce an error. Instead, the field will be ignored and the contact will not be added to the autoresponder cycle. --- # How to schedule a contact import You can schedule a contact import via the [POST /import](https://apireference.getresponse.com/#operation/createImport) method. ## How the method works To import contacts via API, you need a **JSON** file containing your contact details. This way you can **create** and **update** contacts with their **custom fields**. ## What you'll need To schedule a contact import, you'll need to pass the following information: * [Campaign ID](#campaign-id) * [Field mapping](#field-mapping) * [List of contacts to be created or updated](#contacts). ## Campaign ID In GetResponse, you add contacts to a specific campaign (list). To do this, first obtain the campaign (list) ID. There are two ways to find the API-compatible campaign (list) ID: * By looking it up in the **List settings** in your account * Through the API. **Find the campaign (list) ID in List settings** 1. Log into your account. 2. Click **Contacts** or use this [shortcut](https://app.getresponse.com/lists) to display your contact lists. 3. Scroll to find the list. 4. Click the **Actions** icon (vertical elipsis) and select **Settings**. 5. In the **General** tab, you can find the LIST TOKEN value under the **List name** field. **Find the campaign ID through the API** 1. Call the [GET /campaigns](https://apireference.getresponse.com/#operation/getCampaignList) method. 2. Find the target campaign within the JSON response. API-compatible campaign IDs are returned in the `campaignId` fields. ## Field Mapping ```json { "fieldMapping": ["email", "name", "ip", "age", "your_custom_field_1_name", "tag:your_tag_name" ...], } ``` Field mapping specifies what properties to assign to your contacts during an import. It's the equivalent of column headers in a CSV file used to import contacts in a GetResponse account. It **must include** an `email` field. Other contact properties, like `name` and `ip`, as well as custom field names or tag names, can also be included in the mapping. To assign a custom field to a contact you need to provide its value on the corresponding field of the contact array on the `contacts` list. In the API, each custom field has a name. To retrieve the list of your custom fields, you can call the [GET /custom-fields](https://apireference.getresponse.com/#operation/getCustomFieldList) method. A response might look like this: ```json [ { "customFieldId": "y8jnp", "href": "https://api.getresponse.com/v3/custom-fields/y8jnp", "name": "age", "fieldType": "single_select", "valueType": "string", "type": "single_select", "hidden": "false", "values": [ "18-29", "30-44", "45-59", "60+", "<18" ] }, { "customFieldId": "z9Kgt", "href": "https://api.getresponse.com/v3/custom-fields/z9Kgt", "name": "city", "fieldType": "text", "valueType": "string", "type": "text", "hidden": "false", "values": [] } ] ``` This response includes 2 custom fields: age and city. **Note**: **Import API uses custom field names, not IDs.** To assign a tag to a contact you need to properly define it in the `fieldMapping` by adding a `tag:` prefix to a tag name. To retrieve the list of your tags, you can call the [GET /tags](https://apireference.getresponse.com/#operation/getTagsList). You can also add a new tag while importing - just write its new name after a `tag:` prefix. ## Contacts ```json { "contacts": [ ["joe@example.com", "Joe", "127.0.0.1", 55, "Joe's value for custom_field_1", "1",...], ["john@example.com", "John", "192.168.0.1", 20, "John`s value for custom_field_1", "0", ...] ] } ``` The contacts container is a place where the contacts dataset should be specified. Each contact is represented by a separate array. Contact's property values should be placed on the corresponding indexes as their names in `fieldMapping`.  **Note**: **Multi-value custom fields are not fully supported. You can assign only a single value during import.** To assign a tag to a contact, you need to fill the corresponding contact's property values with a string value of either '1' or '0'. A value of '1' indicates that a tag, with a name defined in the fieldMapping, will be attached to the corresponding contact, while a value of '0' means it will not be attached. Currently, there is no possibility to remove tag from a contact using this method. **Note**: **Import API uses tag names, not ID's.** ## Example request payload ```json { "campaignId": "cd2", "fieldMapping": ["email", "name", "ip", "age", "customer_group", "tag:your_new_or_existing_tag_name"], "contacts": [ ["joe@example.com", "Joe", "127.0.0.1", 55, "A", "1"], ["john@example.com", "John", "192.168.0.1", 20, "B", "0"] ] } ``` The above request creates 2 contacts, each with two custom fields. The first one will also have a tag named your_new_or_existing_tag_name attached. ### Response A successful API request returns the HTTP code 201 Created. The response body contains `importId`, statistics, and status. Statistics won't show complete results at this stage because your import has yet to start. To keep track of your import status, use [GET /import](https://apireference.getresponse.com/#operation/getImportById) (provide the `importId` from the response), or subscribe to an [Import finished](../payloads.md#contact-import-finished) webhook. ## Limits * Request can be as big as **20MB.** Larger payloads will be rejected. * You can have **one** active import to one campaign (list) at a time. * You can have **two** active imports in total. The following statuses indicate active imports: `uploaded`, `to_review`, `review` and `approved` * You can create up to **20** imports per **24 hours.** --- # Schedule custom reports To schedule a report, use [POST /custom-reports](https://apireference.getresponse.com/#operation/createCustomReport). The endpoint allows scheduling a custom report of a specific type for a given time period. Depending on the report type, you can also narrow down the data using appropriate filters. **Example request** `/v3/custom-reports` ```json { "name": "Activity Europe", "type": "message_activity_report", "filters": { "activityType": ["click", "open", "send"], "messageId": ["XYZ"] }, "scheduling": { "frequency": "one_time", "startDate": "2024-07-01", "endDate": "2024-08-01" } } ``` **Basic structure** Explanation of `{scheduling}` parameters:
Fields Allowed values Description
frequency one_time Frequency at which the report is generated
startDate UTC date format RFC3339, e.g. "2018-04-10".
Only for "frequency": "one_time".		 The date from which data is collected
endDate UTC date format RFC3339, e.g. "2018-05-10".
Only for "frequency": "one_time".		 The date to which the data is collected
Example: _Generate a report just once for the timeframe spanning from 2024-07-01 to 2024-08-01_ ```json { "name": "Activity Europe", "type": "message_activity_report", "filters": { "activityType": ["click", "open", "send"], "messageId": ["XYZ"] }, "scheduling": { "frequency": "one_time", "startDate": "2024-07-01", "endDate": "2024-08-01" } } ``` ## Report types ## ::: warning Important The reports you can generate depend on your pricing plan. ::: ### subscription_rejections ### _Generate a subscription rejections report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Subscription rejections - may 2024", "type": "subscription_rejections", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### message_stats ### _Generate a message stats report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Message stats - may 2024", "type": "message_stats", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### unsubscribe_contacts_lists_report ### _Generate an unsubscribe contacts lists report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "unsubscribe contacts lists - may 2024", "type": "unsubscribe_contacts_lists_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### standard_subscriber_activity_report ### _Generate a standard subscriber activity report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Standard subscriber activity - may 2024", "type": "standard_subscriber_activity_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### bounces ### _Generate a bounces report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Message bounces - may 2024", "type": "bounces", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### account_summary_report ### _Generate an account summary report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Account summary - may 2024", "type": "account_summary_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### user_activity ### _Generate a user activity report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "User activity - may 2024", "type": "user_activity", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### list_summary_report ### _Generate a list summary report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "List summary - may 2024", "type": "list_summary_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### isp_message_stats_report ### _Generate an isp message stats report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "ISP message stats - may 2024", "type": "isp_message_stats_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### webinar_participants_report ### _Generate a webinar participants report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Webinar participants - may 2024", "type": "webinar_participants_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### import_error_report ### _Generate an import error report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Import errors - may 2024", "type": "import_error_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### message_clicks_report ### _Generate a message clicks report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Message clicks - may 2024", "type": "message_clicks_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### unconfirmed_contacts_stats_report ### _Generate an unconfirmed contacts stats report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Unconfirmed contacts stats - may 2024", "type": "unconfirmed_contacts_stats_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### transactional_email_bounce_report ### _Generate a transactional email bounce report just once for the timeframe spanning from 2024-05-01 to 2024-05-31_ ```json { "name": "Transactional email bounces - may 2024", "type": "transactional_email_bounce_report", "scheduling": { "frequency": "one_time", "startDate": "2024-05-01", "endDate": "2024-05-31" } } ``` ### message_activity_report ### Explanation of `{filters}` parameters:
Fields Allowed values Description
activityType click, open, send Activities the report can include. You can select multiple activities.
messageId Newsletter IDs for which the report is generated. To get messageId, use /v3/newsletters Filter that narrows down the data collected to specific newsletters.
Example: _Generate a newsletter activity report that focuses on clicks or sends for newsletter IDs `abX` or `xyZ`_ ```json { "name": "Activity Test", "type": "message_activity_report", "filters": { "activityType": ["click", "send"], "messageId": ["abX", "xyZ"] }, "scheduling": { "frequency": "one_time", "startDate": "2024-07-01", "endDate": "2024-08-01" } } ``` --- # Custom reports This API lets you find URLs for downloading custom reports in a CSV format. ## Listing To list all your custom reports via API, use [GET /custom-reports](https://apireference.getresponse.com/#operation/getCustomReportList). **Example** ```json [ { "customReportId": "cRi", "name": "Example Report", "href": "https://api.getresponse.com/v3/custom-reports/cRi", "frequency": "daily", "createdAt": "2020-11-20T08:00:00+0000", "generatedAt": "2020-11-20T08:00:00+0000" } ] ``` ## Details To obtain details about specific custom report, you will need `customReportId`. Use the request: [GET /custom-reports/{customReportId}](https://apireference.getresponse.com/#operation/getCustomReportDetails). **Example** ```json { "customReportId": "cRi", "name": "Example Report", "href": "https://api.getresponse.com/v3/custom-reports/cRi", "type": "daily", "scheduling": { "frequency": "one_time", "oneTime": { "startDate": "2020-11-20T08:00:00+0000", "endDate": "2020-11-21T08:00:00+0000" }, "recurring": null }, "createdAt": "2020-11-20T08:00:00+0000", "generatedAt": "2020-11-20T08:00:00+0000", "files": [ { "customReportFileId": "cRiF", "downloadUrl": "https://url/to/file", "status": "ready", "expiresAt": "2020-11-20T08:00:00+0000" } ] } ``` The relations between frequency and other fields within the `scheduling` node are as follows:
frequency oneTime recurring Description
one_time startDate, endDate null For one-time reports, the start and end dates are set and recurring is not available
daily null hour For daily reports, we set recurring by hour as an integer from 0 to 23
weekly null dayOfWeek , hour For weekly reports, we set recurring by dayOfWeek as string (Monday—Sunday) and hour as an integer from 0 to 23
monthly null dayOfMonth , hour For monthly reports, we set recurring by dayOfMonth as an integer from 1 to 31 and hour as an integer from 0 to 23
## How can find out if the report is ready? Webhooks are the most convenient way to receive instant notifications. Create the `generated` [webhook](/v3/payloads#custom-report-s-file-status-changed) to get notified as soon as the report is ready. Alternatively, you can use API to manually check the status of your report using the `getList/getDetails` methods listed above. However, we recommend webhooks for their efficiency and ability to provide real time updates. ## How do I download a report? To download your report, you first need to get its ID `customReportId` using a [webhook](/v3/payloads#custom-report-s-file-status-changed) or by searching the [list of custom reports](https://apireference.getresponse.com/#operation/getCustomReportList). Next, use the customReportId to call [custom report details](https://apireference.getresponse.com/#operation/getCustomReportDetails). The download links are under the `files` node. --- # OAuth 2.0 - Authorization Code OAuth2 (Open Authorization) is an authorization protocol that notifies GetResponse that your application can access data in other GetResponse accounts. For example, you’ve written an application “MyTemplateMaker”. Your client has a GetResponse account and wants to integrate it with your application. For this to happen, you need to register your app with GetResponse and make it possible for the client to authorize **your** application to access **their** account and data. **Note**: * This is a first steps document that explains how to use the `Authorization Code` authorization method. For a comprehensive discussion of OAuth2 methods, go to [documentation](../authentication/oauth2.md). * We suggest you don’t implement `OAuth` from scratch in your application. Instead, you should use a third-party library appropriate to your system architecture, e.g. for [PHP](https://github.com/thephpleague/oauth2-client) with [provider](https://github.com/GetResponse/oauth2-getresponse), [Ruby](https://github.com/oauth-xx/oauth2), or [Python](https://github.com/google/oauth2client). ## Register application and obtain authorization data 1. Visit [Add new application in GetResponse WWW](https://app.getresponse.com/authorizations/add "Add new application in GetResponse WWW") 2. Enter a name, description, and logo of your application. Next, enter a **Redirect URL**. This is the URL to which GetResponse will redirect your client during the authorization process. This should be an URL in **your** domain, for example: `https://mytemplatemaker.example.com/gr_callback` 3. Click **Add**. Your registered app will appear under **Connected applications**. Click on the app name to display: * `Client ID` - This is the “application username”. It identifies your application in the GetResponse system. * `Client secret key` - This is the “application password”. This key **should be strictly confidential and protected**. You need these parameters to obtain the authorization token. When your client wants to use their **GetResponse** account, **your** application should redirect them to the following URL. Be sure to replace client\_ID with **your** `Client ID` value and `random_string` with any random string (this is for security reasons): ```https://app.getresponse.com/oauth2_authorize.html?response_type=code&client_id=client_ID_&state=random_string``` Once redirected to the GetResponse panel, your client will have to log into **their** account and confirm your application’s permissions to access it. Finally, they will be redirected to the URL you set during the application registration, for example: `https://mytemplatemaker.example.com/gr_callback?code=ed17c498bfe343175cd7684c5b09979f2875b25c&state=random_string` You have to handle this request. `random_string` should be equal to the one you sent with the first redirect. `code` is the authorization code you will have to exchange for the token. ## Exchange code for access token You will have to get the token by calling: ```bash curl -u client_id:client_secret https://api.getresponse.com/v3/token \ -d "grant_type=authorization_code&code=ed17c498bfe343175cd7684c5b09979f2875b25c" ``` Replace `client_id` and `client_secret` with the values you received while registering your application. `authorization_code` is the code from the previous (second) redirect. As a response, you will receive: ```json { "access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35", "expires_in": 3600, "token_type": "Bearer", "scope": null, "refresh_token": "170d9f64e781aaa6b3ba036083faba71b2fc4e6c" } ``` Now you can make a request to API, for example: ```bash curl -H "Authorization: Bearer 03807cb390319329bdf6c777d4dfae9c0d3b3c35" https://api.getresponse.com/v3/from-fields ``` ## Refresh token The token is valid for a limited time: `expires_in` value (in seconds). When the token expires, you will receive a `401` response: ```json { "httpStatus": 401, "code": 1014, "codeDescription": "Problem during authentication process, check headers!", "message": "The access token provided is expired", "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1014", "context": { "sentToken": "03807cb390319329bdf6c777d4dfae9c0d3b3c35" } } ``` To refresh the token you will have to make a request using the `refresh_token` value you received when obtaining the token. Example request: ```bash curl -u client_id:client_secret https://api.getresponse.com/v3/token \ -d 'grant_type=refresh_token&refresh_token=170d9f64e781aaa6b3ba036083faba71b2fc4e6c' ``` As a response you will receive another `access_token` and `refresh_token`. Note that the `refresh_token` also expires. If that happens, you will have to redirect your client to their account so that they can allow your application to access their account again. Please refer to the [API documentation](../authentication/oauth2.md) for details. Note that there are some [differences](https://apidocs.getresponse.com/v3/oauth2#GetResponse-Enterprise) for GetResponse MAX accounts. --- # OAuth 2.0 - Client Credentials The `Client Credentials` flow can be used for testing and debugging purposes. You can also use this method to connect your site with your GetResponse account. `Client Credentials` doesn’t require setting `redirect_url` on your server, so this flow is a good starting point for practicing using `GetResponse OAuth`. If you want to access other people’s GetResponse accounts, you need to implement the `Authorization Code` flow. In that flow, the account owner will have to permit your application to access their account. **Note**: * This is a first-steps document, covering the basics of the `Client Credentials` authorization method. For a comprehensive discussion of OAuth2 methods, please refer to the [API documentation](../authentication/oauth2.md). * We suggest you use the [Postman application](https://www.getpostman.com/) as an API test utility (this is a third-party tool commonly used by developers). You can also use the [cURL](https://curl.haxx.se/) library. * We also recommend that you not implement `OAuth` from scratch in your application. Instead, you should use a third-party library appropriate to your system architecture, e.g. for [PHP](https://github.com/thephpleague/oauth2-client) with [provider](https://github.com/GetResponse/oauth2-getresponse), [Ruby](https://github.com/oauth-xx/oauth2), or [Python](https://github.com/google/oauth2client). ## Register application and obtain authorization data 1. Visit [Add new application in GetResponse WWW](https://app.getresponse.com/authorizations/add "Add new application in GetResponse WWW") 2. Enter a name, description, and logo of your application. Next, enter a **Redirect URL**. This is the URL to which GetResponse will redirect your client during the authorization process. This should be an URL in **your** domain, for example: `https://mytemplatemaker.example.com/gr_callback` 3. Click **Add**. Your registered app will appear under **Connected applications**. Click on the app name to display: * `Client ID` - This is the “application username”. It identifies your application in the GetResponse system. * `Client secret key` - This is the “application password”. This key **should be strictly confidential and protected**. You need these parameters to obtain an authorization token. Now you can send a request. Be sure to replace `client_id` and `client_secret_key` with their actual values: ```bash curl -X POST \ -u client_id:client_secret_key \ https://api.getresponse.com/v3/token \ -H 'Content-Type: application/json;charset=utf-8' \ -d '{ "grant_type" : "client_credentials" }' ``` You should get the following response: ```json { "access_token": "ac8839aae", "expires_in": 86400, "token_type": "Bearer", "scope": null } ``` `Access_token` will be a string of letters and numbers. Use the token in the header field `Authorization: Bearer` to authorize any further calls, e.g.: ```bash curl -X GET \ https://api.getresponse.com/v3/campaigns/ \ -H 'Authorization: Bearer ac8839aae' \ -H 'Content-Type: application/json;charset=utf-8' ``` ## Refresh token The token expires in `expires_in` time (given in seconds). Once this happens, you’ll get the following response (`bearer_token_code` is a number you send with request): ```json { "httpStatus": 401, "code": 1014, "codeDescription": "Problem during authentication process, check headers!", "message": "The access token provided is expired", "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1014", "context": { "sentToken": "bearer_token_code" } } ``` You’ll then have to obtain a new token. --- # Segments (search contacts) --- ::: tip Our API v3 uses terminology from the previous version of GetResponse. Search-contacts and segments are the same resource. The phrase search-contacts included in endpoints corresponds to segments in the GetResponse application. ::: Creating targeted search results is an indispensable part of any successful marketing strategy. Using advanced search criteria can help you narrow down your search results so you can reach just the right audience with your emails. You don’t have to create complex conditions from scratch every time you want to use the advanced search criteria. Instead, you can use saved segments. There are two ways to build a segment: - Creating a JSON payload using the filter syntax - Creating a filter in the panel and retrieving the search criteria or contact list. Retrieving an existing segment is a good starting point for working with filters. For information on how to start using the API and the API prerequisites, go to the case study [“Adding contacts”](./adding-contacts). ## Using segments from web panel The easiest way to search for contacts is to create and [save a segment in your account](https://app.getresponse.com/contacts). Then, you can retrieve it using the API. You can use a predefined filter to retrieve a contact list or retrieve the content of the filter as a template for further editing. Log into your account and create a segment as described in [“Managing contacts / How do I create a custom filter?”](https://www.getresponse.com/help/managing-contacts/finding-specific-contacts/what-is-a-custom-filter.html) Enter a descriptive name for your filter. Retrieve the saved filter and get its identifier. Make the request [GET /search-contacts](https://apireference.getresponse.com/#operation/getSearchContactsList) without parameters to get a list of the saved segments. Example response: ```json [ { "searchContactId": "n3FLc", "name": "My_test_customers_list", "createdOn": "2018-04-06T13:05:15+0000", "href": "https://api.getresponse.com/v3/search-contacts/n3FLc" }, { "searchContactId": "n3FLa", "name": "My_other_test_customers_list", "createdOn": "2018-04-06T13:05:15+0000", "href": "https://api.getresponse.com/v3/search-contacts/n3FLa" } ] ``` You will use the value of `searchContactId` to retrieve the contact lists. This is the segment (search contact) identifier. To find a specific saved segment, use the query: [GET /search-contacts/?query[name]=my_test_customers_list](https://apireference.getresponse.com/#operation/getSearchContactsList). With `searchContactId`, make the following request [GET /search-contacts/{searchContactId}/contacts](https://apireference.getresponse.com/#operation/getContactsByIdSearchContacts) to retrieve the list of contacts matching the specified conditions. Example response: ```json [ { "contactId": "V", "href": "https://api.getresponse.com/v3/contacts/V", "name": "John Smith", "email": "jsmith@example.com", "origin": "iphone", "dayOfCycle": "175", "createdOn": "2018-01-01T10:00:00+0000", "campaign": { "campaignId": "V", "name": "TestCampaign", "href": "https://api.getresponse.com/v3/campaigns/V" }, "score": "10", "reason": "unsubscribe", "deletedOn": "2024-02-12T11:00:00+0000" }, { "contactId": "B", "href": "https://api.getresponse.com/v3/contacts/B", "name": "John Harit", "email": "jsmith@example.com", "origin": "iphone", "dayOfCycle": "175", "createdOn": "2018-01-01T10:00:00+0000", "campaign": { "campaignId": "V", "name": "TestCampaign", "href": "https://api.getresponse.com/v3/campaigns/V" }, "score": "10", "reason": "unsubscribe", "deletedOn": "2024-02-12T11:00:00+0000" } ] ``` Please remember that the **results are paginated**. By default, you’ll see the first 100 results. To get more results, you have to request data sequentially using `GET /search-contacts/{searchContactId}/contacts?page=2&perPage=100`, where `page` is the page number and `perPage` is the maximum number of results per page. The default perPage value is 100, maximum: 1000. ## The structure of segment If you want to know the criteria used to create a segment, or to use it as an example to prepare your segment, retrieve the segment by its searchContactId: [GET /search-contacts/{searchContactId}](https://apireference.getresponse.com/#operation/getSearchContactsById). Example response: ```json { "searchContactId": "p", "href": "http://api.getresponse.new/v3/search-contacts/p", "name": "test_conditions", "createdOn": "2018-01-01T10:00:00+0000", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "V" ], "logicOperator": "or", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "email", "operatorType": "string_operator", "operator": "is", "value": "someEmail" }, { "conditionType": "name", "operatorType": "string_operator", "operator": "not_contains", "value": "someName" }, { "conditionType": "geo", "operatorType": "string_operator", "operator": "is_not", "value": "dsaDa", "scope": "country" }, { "conditionType": "custom", "operatorType": "string_operator", "operator": "assigned", "scope": "T" }, { "conditionType": "subscription_date", "operatorType": "date_operator", "operator": "date_to", "value": "2015-01-01" }, { "conditionType": "subscription_method", "method": "webform", "value": "all" }, { "conditionType": "subscription_method", "method": "import", "value": "all" }, { "conditionType": "last_open_date", "operatorType": "date_operator", "operator": "specific_date", "value": "last_30_days" } ] }, { "campaignIdsList": [ "V" ], "logicOperator": "or", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "last_newsletter_date", "operatorType": "date_operator", "operator": "custom", "value": "2015-01-01/2015-01-24" }, { "conditionType": "sent", "operatorType": "message_operator", "operator": "autoresponder", "value": "K" }, { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "splittest", "value": "J" }, { "conditionType": "phase", "operatorType": "numeric_operator", "operator": "numeric_lt", "value": "15" } ] } ] } ``` For `sectionLogicOperator`, the allowed operators are: - `or` for results where any of the sections matches the conditions, - `and` for results where all sections have to match the conditions. `Section` is the equivalent of `Filter group` in the panel. Within every `section` you can build a condition for this group. You can use an `or` or `and` operator as `logicOperator`. This operator works within the appropriate `section` (filter group). In our [reference manual](segments-manual.md) you will find a complete list of fields and operators. ## Adding segments You can create a segment by posting POST /search-contacts/. Example payload: ```json { "name": "test_conditions", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "V" ], "logicOperator": "or", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "email", "operatorType": "string_operator", "operator": "is", "value": "someEmail" }, { "conditionType": "name", "operatorType": "string_operator", "operator": "not_contains", "value": "someName" }, { "conditionType": "geo", "operatorType": "string_operator", "operator": "is_not", "value": "dsaDa", "scope": "country" } ] } ] } ``` The response will contain the segment created: ```json { "searchContactId": "p", "href": "http://api.getresponse.new/v3/search-contacts/p", "name": "test_conditions", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "V" ], "logicOperator": "or", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "email", "operatorType": "string_operator", "operator": "is", "value": "someEmail" }, { "conditionType": "name", "operatorType": "string_operator", "operator": "not_contains", "value": "someName" }, { "conditionType": "geo", "operatorType": "string_operator", "operator": "is_not", "value": "dsaDa", "scope": "country" } ] } ] } ``` ## Executing search without saving a segment You can get a contact list by posting a contact filter payload using [POST /search-contacts/contacts](https://apireference.getresponse.com/#operation/getContactsFromSearchContactsConditions). This won’t create a new saved filter - the API will return just the contact list. Example payload: ```json { "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "V" ], "logicOperator": "or", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "email", "operatorType": "string_operator", "operator": "is", "value": "someEmail" }, { "conditionType": "name", "operatorType": "string_operator", "operator": "not_contains", "value": "someName" }, { "conditionType": "geo", "operatorType": "string_operator", "operator": "is_not", "value": "dsaDa", "scope": "country" } ] } ] } ``` ## Other operations See our [reference manual](https://apireference.getresponse.com/#tag/Search-Contacts) for a complete list of operations, including `deleting` and `assigning custom fields` to contacts that match the filter conditions. --- # Segments (search contacts) reference manual ::: tip Our API v3 uses terminology from the previous version of GetResponse. Search-contacts and segments are the same resource. The phrase search-contacts included in endpoints corresponds to segments in the GetResponse application. ::: The 'searchContacts' method returns complex responses from our resources. It lets you create and run precise search queries. In this document, we explain how it works and how to use it. Table of contents 1. [A short description of the available resources](#short-description) 1. [`/v3/search-contacts/contacts` using segment queries](#get-all-contacts-from-search-contacts) - [Basics](#basic-search-contacts) - [Contact details](#create-contact-details-search-contacts) - [Name](#get-by-name-search-contacts) searching for contacts by name. - [Email](#get-by-email-search-contacts) searching for contacts by email. - [Custom fields](#get-by-custom-fields-search-contacts) searching for contacts by predefined custom fields. - [Subscription date](#get-by-subscription-date-search-contacts) searching for contacts by subscription date. - [Subscription method](#get-by-subscription-method-search-contacts) searching for contacts by subscription method. - [Contact actions](#create-contact-actions-search-contacts) - [Message opened](#opened-action) finding contacts who opened a specific message. - [Message not opened](#not-opened-action) finding contacts who didn't open a specific message. - [Autoresponder day](#autoresponder-day-action) finding contacts who are on a specific day in an autoresponder cycle. - [Last send date](#last-send-date-action) finding contacts based on when an email was last sent. - [Last click date](#last-click-date-action) finding contacts based on when they last clicked a message. - [Last open date](#last-open-date-action) finding contacts based on when they last opened a message. - [Webinars](#webinars-action) finding webinar participants. - [Link clicked](#link-clicked-action) finding contacts who clicked a link in a message. - [Link not clicked](#link-not-clicked-action) finding contacts who didn't click a link. - [Message sent](#message-sent-action) finding contacts who were sent a specific message. - [Message not sent](#message-not-sent-action) finding contacts were never sent a specific message. - [Geolocation](#create-geolocation-search-contacts) - [GDPR](#create-gdpr-search-contacts) - [Scoring](#create-scoring-search-contacts) - [Engagement Score](#create-engagement-score-search-contacts) - [Tags](#create-tags-search-contacts) - [Ecommerce](#create-ecommerce-search-contacts) - [`ecommerce_number_of_purchases` searching for contacts by the number of purchases they've made.](#ecommerce-number-of-purchases-condition-type) - [`ecommerce_total_spent` searching for contacts by total spent.](#ecommerce-total-spent-condition-type) - [`ecommerce_product_purchased` searching for contacts by products purchased.](#ecommerce-product-purchased-condition-type) - [`ecommerce_brand_purchased` searching for contacts by brand purchased.](#ecommerce-brand-purchased-condition-type) - [`ecommerce_abandoned_cart` searching for contacts by abandoned cart.](#ecommerce-abandoned-cart-condition-type) - [SMS (Text messaging)](#create-sms-search-contacts) - [`sms_sent` finding contacts who were sent a specific SMS.](#sms-sent-condition-type) - [`sms_link_clicked` finding contacts who clicked a specific link.](#sms-link-clicked-condition-type) - [`sms_link_not_clicked` finding contacts who didn't click a specific link.](#sms-link-not-clicked-condition-type) - [Custom Events](#create-custom-events-search-contacts) - [Search-contact response](#search-contacts-response) 1. [`/v3/search-contacts` creating search criteria for later re-use.](#create-search-contacts) 1. [`/v3/search-contacts` retrieving existing segments.](#get-search-contacts) 1. [`/v3/search-contacts/{searchContactId}` retrieving search criteria used in a specific segment.(#get-search-contacts-by-id) 1. [`/v3/search-contacts/{searchContactId}` updating a segment.](#update-search-contacts) 1. [`/v3/search-contacts/{searchContactId}` deleting a segment.](#delete-search-contacts) 1. [`/v3/search-contacts/{searchContactId}/contacts` retrieving the list of contacts matching the search criteria.](#get-all-contacts-from-search-contacts-by-id) 1. [`/v3/search-contacts/{searchContactId}/custom-fields` adding or updating custom field values for all contacts who meet specific search criteria.](#custom-fields-search-contacts-by-id) **Appendices** 1. [Full list of operator types](#appendix-a) 1. [Full list of currencies](#appendix-b) 1. [API requests query parameters](#appendix-c) ## Short description of resources. {#short-description} List of available resources ### `/v3/search-contacts` **Available HTTP methods (endpoints):** [](#get-search-contacts) [](#create-search-contacts) We suggest you first explore the [Advanced search](https://www.getresponse.com/help/getting-started-with-getresponse/how-do-i-search-for-contacts.html) options in your GetResponse account. **Advanced search** lets you add up to 8 conditions and 8 condition groups. You can make your search as broad or narrow as you'd like using different combinations of conditions, condition groups, and the available condition and group connectives. You can store the search criteria for future use, and you can save them as a segment. Contacts who match the criteria are dynamically added to the search results. Once you've created a segment in your account, you can analyze the response fetched from [`/v3/search-contacts/{searchContactId}`](#get-search-contacts-by-id). --- ### `/v3/search-contacts/{searchContactId}` Use the resource with an identifier to get, update, or delete the conditions used to create the specific segment. **Available HTTP methods (endpoints):** [](#get-search-contacts-by-id) [](#update-search-contacts) [](#delete-search-contacts) --- ### `/v3/search-contacts/{searchContactId}/contacts` Use the search contacts resource to get all the contacts matching the search criteria used in a given segment. **Available HTTP methods (endpoints):** [](#get-all-contacts-from-search-contacts-by-id) --- ### `/v3/search-contacts/contacts` Use the resource to search for contacts by direct query. **Available HTTP methods (endpoints):** [](#get-all-contacts-from-search-contacts) --- ### `/v3/search-contacts/{searchContactId}/custom-fields` Use the resource to add or update custom field values for all contacts who meet the search criteria **Available HTTP methods (endpoints):** [](#custom-fields-search-contacts-by-id) --- Table of available endpoints
Method Endpoint Usage
[/v3/search-contacts](#get-search-contacts) retrieving created segments
[/v3/search-contacts](#create-search-contacts) creating a new segment
[/v3/search-contacts/contacts](#get-all-contacts-from-search-contacts) search for contacts without saving the search
[/v3/search-contacts/{searchContactId}](#get-search-contacts-by-id) retrieving the search criteria used in a specific segment
[/v3/search-contacts/{searchContactId}](#update-search-contacts) updating a segment
[/v3/search-contacts/{searchContactId}](#delete-search-contacts) deleting a segment
[/v3/search-contacts/{searchContactId}/contacts](#get-all-contacts-from-search-contacts-by-id) retrieving the list of contacts filtered by specific segment
[/v3/search-contacts/{searchContactId}/custom-fields](#custom-fields-search-contacts-by-id) adding and updating custom field values for all contacts who meet the specific search criteria
## Get the contacts matching specific conditions. {#get-all-contacts-from-search-contacts} This endpoint lets you get the contacts matching specific conditions. This section explains how to create search conditions. **Example request** `v3/search-contacts/contacts` ```json { "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "logicOperator": "and", "conditions": [ { "conditionType": "name", "operatorType": "string_operator", "operator": "contains", "value": "John" } ] } ] } ``` **Example response** ```json [ { "contactId": "jtLF5i", "href": "https://default_server/v3/contacts/jtLF5i", "name": "JohnSmith", "email": "johnsmith@example.com", "origin": "landing_page", "dayOfCycle": "108", "createdOn": "2018-01-15T13:30:42+0000", "campaign": { "campaignId": "tamqY", "name": "TestCampaign", "href": "https://api.getresponse.com/v3/campaigns/tamqY" }, "score": null, "reason": null, "deletedOn": null } ] ``` You can limit the fetched set of fields by adding query parameters described [here](#appendix-c). ### Basics {#basic-search-contacts} **Example request** `v3/search-contacts/contacts` ```json { "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "logicOperator": "and", "conditions": [] } ] } ``` The main search-contact request (segment) is built of 3 fields. **Basic structure of request** ```json { "subscribersType": , "sectionLogicOperator": "{sectionLogicOperator}", "section": } ```
Value Description
`` An array with the following values: - `"subscribed"` - subscribed contacts, - `"undelivered"`, - `"removed"` - unsubscribed contacts, - `"unconfirmed"`
`{sectionLogicOperator}` Enum(`or`, `and`), match 'any' or 'all' of the conditions specified.
`` A collection of `section-item` describing the search conditions. Maximum 8 sections are allowed. At least one section is required.
**Basic structure of** `` ```json { "campaignIdsList": , "subscriberCycle": , "subscriptionDate": "{subscriptionDate}", "customDate": { "from": "{utcDateFormat}", "to": "{utcDateFormat}" }, "logicOperator": "{conditionLogicOperator}", "conditions": } ``` The field `"customDate"` is required only for `"subscriptionDate": "custom"`. You can use up to 8 sections per request. **Fields description**
Field Value Description
`` `array of strings` An array of campaign identifiers from [/v3/campaigns.](https://apireference.getresponse.com/#operation/getCampaignList)
`` `array of strings` An array of following values: `receiving_autoresponder`, `not_receiving_autoresponder` determining whether or not a contact has been added to an autoresponder cycle.
`{subscriptionDate}` `all_time`, `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_week`, `last_week,this_month`, `last_month`, `last_2_months`, `custom` Matches the corresponding period. For `custom` field `"customDate"` is required.
`{utcDateFormat}` UTC date format [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6), e.g. "2018-04-10". Field `"customDate"` is required only for `"subscriptionDate": "custom"`.
`{conditionLogicOperator}` `or`, `and` Match 'any' or 'all' of the following conditions
`` `collection of ` A collection defining the condition. Up to 8 conditions are allowed.
Conditions used in segments help you narrow down your search results to a specific group of contacts. In the following sections we explain how you can create conditions to quickly identify the contacts you're looking for. **Examples** _Find all contacts who were removed from a specific list._ ```json { "subscribersType": [ "removed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "o5lx" ], "logicOperator": "or", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time" } ] } ``` ### Contact details {#create-contact-details-search-contacts} Searching for contacts based on their contact details
Condition Description
[Name](#get-by-name-search-contacts) searching for contacts by name
[Email](#get-by-email-search-contacts) searching for contacts by email
[Custom fields](#get-by-custom-fields-search-contacts) searching for contacts by predefined custom fields
[Subscription date](#get-by-subscription-date-search-contacts) searching for contacts by subscription date
[Subscription method](#get-by-subscription-method-search-contacts) searching for contacts by subscription method
--- #### Name - searching by name of contact {#get-by-name-search-contacts} To find contacts by name, use ```json "conditionType": "name" ``` with ```json "operatorType": "string_operator" ``` Example condition: ```json { "conditionType": "name", "operatorType": "string_operator", "operator": "contains", "value": "John" } ``` Basic structure of name condition: ```json { "conditionType": "name", "operatorType": "string_operator", "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends", "value": "" } ``` Table of allowed values and operators:
`operatorType` Allowed operators Allowed values
`string_operator` `is`, `is_not`, `contains`, `not_contains`, `starts`, `ends`, `not_starts`, `not_ends` ``
You can find detailed information about `"operatorType": "string_operator"` [here](#appendix-a). --- #### Email - search by email of contact {#get-by-email-search-contacts} To find contacts by email, use ```json "conditionType": "email" ``` with ```json "operatorType": "string_operator" ``` Example condition: _Find all contacts whose email address includes "john"._ ```json { "conditionType": "email", "operatorType": "string_operator", "operator": "contains", "value": "john" } ``` Basic structure of email condition: ```json { "conditionType": "email", "operatorType": "string_operator", "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends", "value": "" } ``` Table of allowed fields and their values:
`operatorType` Allowed operators Allowed values
`string_operator` `is`, `is_not`, `contains`, `not_contains`, `starts`, `ends`, `not_starts`, `not_ends` ``
You can find detailed information about `"operatorType": "string_operator"` [here](#appendix-a). --- #### Custom fields - searching contacts by custom fields {#get-by-custom-fields-search-contacts} To find contact by custom field, use ```json "conditionType": "custom" ``` To use custom fields in your search, you need to fetch their identifiers and possible values from [/v3/custom-fields](https://apireference.getresponse.com/#operation/getCustomFieldList). If field accepts **string values**, check whether custom field accepts **single value** or **multiple values**. For single value use `"operatorType": "string_operator"`. For multiple values use `"operatorType": "string_operator_list"` Example condition: _Find all contacts with the custom field "country" set to "Canada"._ ```json { "conditionType": "custom", "scope": "pa3Ih", "operatorType": "string_operator_list", "operator": "is", "value": "Canada" } ``` This custom field has multiple string values, so `"operatorType": "string_operator_list"` have to be used. `"scope": "pa3N6"` specifies the ID of the custom field Possible structures of custom condition: All custom fields with `"operator": "assigned"` or `"operator": "not_assigned"`: ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "string_operator|string_operator_list|date_operator|numeric_operator", "operator": "assigned|not_assigned" } ``` String based custom fields with all operators except `"operator": "assigned"` and `"operator": "not_assigned"`: ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "string_operator|string_operator_list", "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends", "value": "{stringValue}" } ``` Date based custom fields with `"operator": "specific_date"`: ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "date_operator", "operator": "specific_date", "value": "today|yesterday|last_n_days|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month" } ``` For the specific `"value": "last_n_days"` structure of condition is extended by two parameters. ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "date_operator", "operator": "specific_date", "value": "last_n_days", "numberOfDays": "", "includeCurrentPeriod": "" } ``` Field `"numberOfDays"` required only for `"value": "last_n_days"`. Field `"includeCurrentPeriod"` is optional and used only with `"value": "last_n_days"`. Table of allowed fields and their values:
value allowed values
today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month field "numberOfDays" prohibited
last_n_days <integer>
Table of relation between value and includeCurrentPeriod:
value is includeCurrentPeriod allowed
today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month field "includeCurrentPeriod" prohibited
last_n_days <boolean>
Date based custom fields with `"operator": "date_to"` or `"operator": "date_from"`: ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "date_operator", "operator": "date_to|date_from", "value": "{utcDateFormat}" } ``` **`{utcDateFormat}`** is a UTC date format, read more in RFC3339, e.g. "2018-04-10" Date based custom fields with `"operator": "custom"`: ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "date_operator", "operator": "custom", "value": "{rangeUTCDateFormat}" } ``` `{rangeUTCDateFormat}` is a ISO8601 format date interval, i.e. `"date_from/date_to"` where `date_from` and `date_to` are in the UTC format, read more in RFC3339. e.g. "2018-04-02/2018-04-23" Number based custom fields with all operators except `"operator": "assigned"` and `"operator": "not_assigned"`: ```json { "conditionType": "custom", "scope": "{customFieldId}", "operatorType": "numeric_operator", "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq", "value": "{numericValue}" } ``` Some predefined custom fields can be fetched using /v3/custom-fields. See the table below for the available operator types for predefined custom fields.
Custom field name Operator type
age
country
gender		 string_operator_list
birthday date_operator
city
comment
company
fax
home_phone
http_referer
mobile_phone
phone
postal_code
ref
state
street
url
work_phone		 string_operator
Find more information about possible values of **`"operatorType"`** in Appendix A. Example age condition: _Find all contacts with the custom field "age" set to "18-29"._ ```json { "conditionType": "custom", "scope": "pa37y", "operatorType": "string_operator_list", "operator": "is", "value": "18-29" } ``` Example country condition: _Find all contacts with the custom field "country" set to "Canada"._ ```json { "conditionType": "custom", "scope": "pa3Ih", "operatorType": "string_operator_list", "operator": "is", "value": "Canada" } ``` Example birthday condition: _Find all contacts with the custom field "birthday" set to between 1970-01-01 and 1979-12-31._ ```json { "conditionType": "custom", "scope": "pa3Lo", "operatorType": "date_operator", "operator": "custom", "value": "1970-01-01/1979-12-31" } ``` Example condition with string_operator: ```json { "conditionType": "custom", "scope": "pa3Ui", "operatorType": "string_operator", "operator": "starts", "value": "new" } ``` --- #### Subscription date - searching contact by date of subscription {#get-by-subscription-date-search-contacts} To search contacts by subscription date, use ```json "conditionType": "subscription_date" ``` with ```json "operatorType": "date_operator" ``` Example condition: _Find all contacts who subscribed between 2018-04-01 and 2018-04-30._ ```json { "conditionType": "subscription_date", "operatorType": "date_operator", "operator": "custom", "value": "2018-04-01/2018-04-30" } ``` Basic structure of subscription date condition: ```json { "conditionType": "subscription_date", "operatorType": "date_operator", "operator": "date_to|date_from|specific_date|custom", "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}" } ``` Table of allowed fields and their values:
operatorType Allowed operators Allowed values
date_operator date_to, date_from {utcDateFormat}
  specific_date today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
  custom {rangeUTCDateFormat}
  assigned, not_assigned field "value" prohibited
Value Description
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "operator": "date_to|date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "operator": "custom".
You can find detailed information about **`"operatorType": "date_operator"`** [here](#appendix-a). --- #### Subscription method - searching contact by method of subscription {#get-by-subscription-method-search-contacts} Find contacts by subscription methods Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "webform|import|landing_page|api|email|panel|mobile|survey|sales|copy|leads|webinar|chat|website_builder_elegant|course|premium_newsletter", "webformType": "all|webforms|webformsv2|popups", "value": "all|{webformsId}|{webformsv2Id}|{popupsUuid}|{importId}|{landingPageId}|{webinarId}|{websiteUuid}" } ``` The field `"value"` is prohibited with `"webformType": "all"`.
method Description
webform Sign-up via legacy form
import Added via import
landing_page Added via landing page
api Added via api
email Sign-up via list email address
panel Added manually
mobile Sign-up via mobile app
survey Sing-up via survey
copy Copied from other list
leads Added via GetSubscribers.com
webinar Added via webinar
chat Added via GR Chat App
website_builder_elegant Added via website
course Added via course
premium_newsletter Added via paid newsletter
##### webform {#method-webform} Search for contacts who subscribed via a legacy form Example condition: _Find all contacts who subscribed by any legacy form._ ```json { "conditionType": "subscription_method", "method": "webform", "webformType": "all" } ``` Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "webform", "webformType": "all|webforms|webformsv2|popups", "value": "{webformId}|{webformv2Id}|{popupUuid}" } ``` The field **`"value"`** is prohibited for `"webformType": "all"`.
Value Description
{webformId} Legacy form identifier can be fetched from GET /v3/webforms
{webformv2Id}  
{popupUuid} Popup identifier can be fetched from GET /v3/popups
Example conditions: _Find all contacts who subscribed via a specific webform._ ```json { "conditionType": "subscription_method", "method": "webform", "webformType": "webformsv2", "value": "PSO39" } ``` ##### import {#method-import} Find imported contacts Example condition: _Find all imported contacts_ ```json { "conditionType": "subscription_method", "method": "import", "value": "all" } ``` Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "import", "value": "all|{importId}" } ```
Value Description
{importId} Import identifier can be fetched from GET /v3/imports
##### landing page {#method-landing-page} Find contact who subscribed via landing page. Example condition: _Find all contacts who signed up through a specific landing page._ ```json { "conditionType": "subscription_method", "method": "landing_page", "value": "XXqi" } ``` Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "landing_page", "value": "all|{landingPageId}" } ```
Value Description
{landingPageId} Landing page identifier can be fetched from GET /v3/landing-pages
##### api {#method-api} Find contact subscribed via API. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "api" } ``` ##### email {#method-email} Find contacts who signed up through list email address. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "email" } ``` ##### panel {#method-panel} Find contacts added manually. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "panel" } ``` ##### mobile {#method-mobile} Find contacts who signed up via mobile app. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "mobile" } ``` ##### survey {#method-survey} Find contacts who subscribed via survey. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "survey" } ``` ##### sales {#method-sales} Find contacts who subscribed through sales. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "sales" } ``` ##### copy {#method-copy} Find contacts copied from other list. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "copy" } ``` ##### leads {#method-leads} To find contact subscribed through leads. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "leads" } ``` ##### webinar {#method-webinar} To find contacts subscribed through webinar. Example condition: _Find all contacts who subscribed by any webinar._ ```json { "conditionType": "subscription_method", "method": "webinar", "value": "all" } ``` Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "webinar", "value": "all|{webinarId}" } ```
Value Description
{webinarId} Webinar identifier can be fetched from /v3/webinars
##### chat {#method-chat} Find contacts who subscribed through the GR Chat application. Example condition: _Find all contacts subscribed via GR Chat._ ```json { "conditionType": "subscription_method", "method": "chat" } ``` ##### website {#method-website_builder_elegant} Find contacts subscribed using a form embedded on website created with the GR website builder. Example condition: _Find all contacts subscribed via websites._ ```json { "conditionType": "subscription_method", "method": "website_builder_elegant", "value": "all" } ``` _Find contacts subscribed via specific website._ ```json { "conditionType": "subscription_method", "method": "website_builder_elegant", "value": "123e4567-e89b-12d3-a456-426614174000" } ``` Basic structure of condition: ```json { "conditionType": "website_builder_elegant", "method": "webinar", "value": "all|{websiteUUID}" } ```
Value Description
{websiteUUID} Website identifier. It can be found using method: /v3/websites
##### course {#method-course} Find contact subscribed via a course. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "course" } ``` ##### premium_newsletter {#method-premium_newsletter} Find contacts who signed up via a paid newsletter. Basic structure of condition: ```json { "conditionType": "subscription_method", "method": "premium_newsletter" } ``` ### Contact actions {#create-contact-actions-search-contacts}
Action conditionType operatorType Description
Message opened "opened" "message_operator" To find contacts who opened a specific message.
Message not opened "not_opened" "complex_message_operator" To find contacts who didn't open a message.
Autoresponder day "phase" "numeric_operator" To find contacts on a specific day in an autoresponder cycle.
Last send date "last_send_date" "date_operator" To find contacts based on the date an email was last sent to them.
Last click date "last_click_date" "date_operator" To find contacts based on the date they last clicked a link in an email.
Last open date "last_open_date" "date_operator" To find contacts based on the date they last opened an email.
Webinars "webinar"    
Link clicked "clicked" "message_operator" To find contacts who clicked a link.
Link not clicked "not_clicked" "complex_message_operator" To find contacts who didn't click a link.
Message sent "sent" "message_operator" To find contacts who were sent a specific email.
Message not sent "not_sent" "message_operator" To find contacts who were not sent a specific email.
--- #### Message opened {#opened-action} Example condition: _Find contacts who opened a specific email._ ```json { "conditionType": "opened", "operatorType": "message_operator", "operator": "autoresponder", "value": "SGNLr" } ``` Basic structure of condition: ```json { "conditionType": "opened", "operatorType": "message_operator", "operator": "newsletter|autoresponder|splittest|automation", "value": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}" } ``` You can find detailed information about **`"operatorType": "message_operator"`** here. --- #### Message not opened {#not-opened-action} Find contacts who didn't open a specific email. Example condition: ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "autoresponder", "scope": "xyz", "dateOperator": "never" } ``` Basic structure of condition: ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "all|autoresponder|newsletter|splittest|automation", "scope": "{autoresponderId}|{newsletterId}|{splittestId}|{automationId}", "dateOperator": "never|date_from|today|yesterday|last_7_days|last_30_days|last_n_days|this_week|this_month", "value": "{utcDateFormat}|", "includeCurrentPeriod": "" } ``` For the specific "scope", set {autoresponderId}|{newsletterId}|{splittestId}|{automationId} otherwise the "scope" field is prohibited. Field **`"value"`** required only for **`"dateOperator": "date_from|last_n_days"`**, for others **`"dateOperator"`** it is prohibited. Table of allowed fields and their values:
dateOperator allowed values
never, today, yesterday, last_7_days, last_30_days, this_week, this_month field "value" prohibited
date_from {utcDateFormat}
last_n_days <integer>
Table of relation between dateOperator and includeCurrentPeriod
dateOperator is includeCurrentPeriod allowed
never, today, yesterday, this_week, this_month field "includeCurrentPeriod" prohibited
last_7_days, last_30_days, last_n_days <boolean>
Value Description
{autoresponderId} To find {autoresponderId} use /v3/autoresponders
{newsletterId} To find {newsletterId} use /v3/newsletters
{splittestId} To find {splittestId} use /v3/newsletters?query[type]=splittest
{automationId} To find {automationId} use /v3/newsletters?query[type]=automation
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "operator": "date_from"
Example conditions: _Find contacts who have never opened any messages._ ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "all", "dateOperator": "never" } ``` _Find contacts who haven't opened any message for the last 10 days including today._ ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "all", "dateOperator": "last_n_days", "value": "10", "includeCurrentPeriod": true } ``` _Find contacts who haven't opened a specific newsletter today._ ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "newsletter", "dateOperator": "today", "scope": "z4Zje" } ``` You can find detailed information about **`"operatorType": "complex_message_operator"`** here. --- #### Autoresponder day {#autoresponder-day-action} Find contacts by autoresponder day Example condition: _Find contacts who are on a specific day of the autoresponder cycle._ ```json { "conditionType": "phase", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "6" } ``` Basic structure of condition: ```json { "conditionType": "phase", "operatorType": "numeric_operator", "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq|assigned|not_assigned", "value": "" } ``` Table of allowed fields and their values:
operatorType Allowed operators Allowed values
numeric_operator numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq <integer>
  assigned, not_assigned field "value" prohibited
You can find detailed information about **`"operatorType": "numeric_operator"`** here. --- #### Last send date {#last-send-date-action} Find contacts based on the date they were last sent an email. Example condition: _Find contacts who've been sent an email within the last seven days._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "specific_date", "value": "last_7_days" } ``` Basic structure of condition: ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "date_to|date_from|specific_date|custom", "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}" } ``` Table of allowed fields and their values:
operatorType Allowed operators Allowed values
date_operator specific_date today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
  date_to, date_from {utcDateFormat}
  custom {rangeUTCDateFormat}
Value Description
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "operator": "date_to|date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "operator": "custom".
You can find detailed information about **`"operatorType": "date_operator"`** here. Example conditions: _Find contacts who were sent a newsletter before 2018-05-06._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "date_to", "value": "2018-05-06" } ``` _Find contacts who were sent an email message after 2018-05-06._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "date_from", "value": "2018-05-15" } ``` _Find contacts who were sent an email message in the last seven days._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "specific_date", "value": "last_7_days" } ``` _Find contacts who were sent an email message between 2018-05-01 and 2018-05-31._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "custom", "value": "2018-05-01/2018-05-31" } ``` --- #### Last click date {#last-click-date-action} Find contacts based on the last time they clicked a message. Example condition: _Find contacts who clicked a message before 2018-04-30._ ```json { "conditionType": "last_click_date", "operatorType": "date_operator", "operator": "date_to", "value": "2018-04-30" } ``` Basic structure of condition: ```json { "conditionType": "last_click_date", "operatorType": "date_operator", "operator": "date_to|date_from|specific_date|custom", "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}" } ``` Table of allowed fields and their values:
operatorType Allowed operators Allowed values
date_operator specific_date today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
  date_to, date_from {utcDateFormat}
  custom {rangeUTCDateFormat}
Value Description
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "operator": "date_to|date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "operator": "custom".
You can find detailed information about **`"operatorType": "date_operator"`** here. Example conditions: _Find contacts who clicked a message after 2018-05-15._ ```json { "conditionType": "last_click_date", "operatorType": "date_operator", "operator": "date_from", "value": "2018-05-15" } ``` _Find contacts who have clicked a message in the last week._ ```json { "conditionType": "last_click_date", "operatorType": "date_operator", "operator": "specific_date", "value": "last_week" } ``` _Find contacts who clicked a message between 2018-05-01 and 2018-05-31"._ ```json { "conditionType": "last_click_date", "operatorType": "date_operator", "operator": "custom", "value": "2018-05-01/2018-05-31" } ``` --- #### Last open date {#last-open-date-action} Find contacts based on when they last opened an email. Example condition: _Find contacts who opened a message this week._ ```json { "conditionType": "last_open_date", "operatorType": "date_operator", "operator": "specific_date", "value": "this_week" } ``` Basic structure of condition: ```json { "conditionType": "last_open_date", "operatorType": "date_operator", "operator": "date_to|date_from|specific_date|custom", "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}" } ``` Table of allowed fields and their values:
operatorType Allowed operators Allowed values
date_operator specific_date today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
  date_to, date_from {utcDateFormat}
  custom {rangeUTCDateFormat}
Value Description
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "operator": "date_to|date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "operator": "custom".
You can find detailed information about **`"operatorType": "date_operator"`** here. Example conditions: _Find contacts who opened a message before 2018-05-01._ ```json { "conditionType": "last_open_date", "operatorType": "date_operator", "operator": "date_to", "value": "2018-05-01" } ``` _Find contacts who opened a message after 2018-05-01._ ```json { "conditionType": "last_open_date", "operatorType": "date_operator", "operator": "date_from", "value": "2018-05-01" } ``` _Find contacts who opened a message between 2018-05-07 and 2018-05-29._ ```json { "conditionType": "last_open_date", "operatorType": "date_operator", "operator": "custom", "value": "2018-05-07/2018-05-29" } ``` --- #### Webinars {#webinars-action} Find contacts cased on participation in a specific webinar as a host, listener, presenter, registrant, or any user. Example condition: _Find contacts who participated as a presenter during a specific webinar._ ```json { "conditionType": "webinar", "scope": "MNAR", "webinarCondition": "participated", "contactType": "presenter", } ``` Basic structure of condition: ```json { "conditionType": "webinar", "scope": "{webinarId}", "webinarCondition": "participated|not_participated", "contactType": "host|listener|presenter|registrant|all" } ```
Value Description
{webinarId} Webinar identifier can be fetched from /v3/webinars
--- #### Link clicked {#link-clicked-action} To find contacts that clicked on the link. Example condition: _Find contacts who clicked any link in a specific autoresponder email._ ```json { "conditionType": "clicked", "operatorType": "message_operator", "operator": "autoresponder", "scope": "SGNLr", "clickTrackId": "all" } ``` Basic structure of condition: ```json { "conditionType": "clicked", "operatorType": "message_operator", "operator": "autoresponder|newsletter|splittest|automation", "scope": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}", "clickTrackId": "all|{clickTrackId}" } ```
Value Description
{autoresponderId} To find {autoresponderId} use /v3/autoresponders
{newsletterId} To find {newsletterId} use /v3/newsletters
{splittestId} To find {splittestId} use /v3/newsletters?query[type]=splittest
{automationId} To find {automationId} use /v3/newsletters?query[type]=automation
{clickTrackId} To find {clickTrackId} fetch message details. i.e. /v3/newsletter/{newsletterId} or use /v3/click-tracks
You can find detailed information about **`"operatorType": "message_operator"`** here. Example conditions: _Find contacts who clicked a specific link in a specific autoresponder email._ ```json { "conditionType": "clicked", "operatorType": "message_operator", "operator": "autoresponder", "scope": "SGNLr", "clickTrackId": "PPxJw9" } ``` _Find contacts who clicked any link in a specific newsletter._ ```json { "conditionType": "clicked", "operatorType": "message_operator", "operator": "newsletter", "scope": "zlrzy", "clickTrackId": "all" } ``` _Find contacts who clicked a specific link in a specific newsletter._ ```json { "conditionType": "clicked", "operatorType": "message_operator", "operator": "newsletter", "scope": "zlrzy", "clickTrackId": "P1Ssv5" } ``` --- #### Link not clicked {#link-not-clicked-action} Find contacts who didn't click a link. Example condition: ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "all", "dateOperator": "never" } ``` Basic structure of condition: ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "all|autoresponder|newsletter|splittest|automation", "dateOperator": "date_from|today|yesterday|last_7_days|last_30_days|last_n_days|this_week|last_week|this_month", "scope": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}", "clickTrackId": "all|{clickTrackId}", "value": "{utcDateFormat}|", "includeCurrentPeriod": "" } ``` For the specific "scope", set {autoresponderId}|{newsletterId}|{splittest-id}|{automationId} otherwise the "scope" field is prohibited. Field **`"value"`** required only for **`"dateOperator": "date_from|last_n_days"`**, for others **`"dateOperator"`** it is prohibited. Table of allowed fields and their values:
dateOperator allowed values
never, today, yesterday, last_7_days, last_30_days, this_week, this_month field "value" prohibited
date_from {utcDateFormat}
last_n_days <integer>
Table of relation between dateOperator and includeCurrentPeriod:
dateOperator is includeCurrentPeriod allowed
never, today, yesterday, this_week, this_month field "includeCurrentPeriod" prohibited
last_7_days, last_30_days, last_n_days <boolean>
Field "clickTrackId" required only if specific scope is defined.
Value Description
{newsletterId} Newsletter identifier can be fetched from /v3/newsletters
{autoresponderId} Autoresponder identifier can be fetched from /v3/autoresponders
{splittestId} Splittest identifier can be fetched from /v3/newsletters?query[type]=splittest
{automationId} To find {automationId} use /v3/newsletters?query[type]=automation
{clickTrackId} To find {clickTrackId} fetch message details. i.e. /v3/newsletter/{newsletterId} or use /v3/click-tracks
Example conditions: _Find contacts who have never clicked any links._ ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "all", "dateOperator": "never" } ``` _Find contacts who haven't clicked any link in an autoresponder email since 05/06/2018._ ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "autoresponder", "dateOperator": "date_from", "value": "2018-05-06" } ``` _Find contacts who haven't clicked any link in a specific newsletter today._ ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "newsletter", "dateOperator": "today", "scope": "zhgnQ", "clickTrackId": "all" } ``` _Find contacts who haven't clicked a specific link in a specific splittest in the last 20 days including today._ ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "splittest", "dateOperator": "last_n_days", "scope": "zSp9V", "value": "20", "clickTrackId": "PPxiOW", "includeCurrentPeriod": true } ``` --- #### Message sent {#message-sent-action} Find contacts who were sent a specific message. Example condition: _Find contacts who were sent a specific splittest._ ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "splittest", "value": "zSp9V" } ``` Basic structure of condition: ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "newsletter|autoresponder|splittest|automation", "value": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}" } ```
Value Description
{autoresponderId} To find {autoresponderId} use /v3/autoresponders
{newsletterId} To find {newsletterId} use /v3/newsletters
{splittestId} To find {splittestId} use /v3/newsletters?query[type]=splittest
{automationId} To find {automationId} use /v3/newsletters?query[type]=automation
You can find detailed information about **`"operatorType": "message_operator"`** here. Example conditions: _Find contacts who were sent a specific autoresponder email._ ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "autoresponder", "value": "SY6kx" } ``` _Find contacts who were sent a specific newsletter._ ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "newsletter", "value": "z4Zje" } ``` _Find contacts who were sent a specific splittest._ ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "splittest", "value": "zSp9V" } ``` _To find contacts who were sent a specific automation message._ ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "automation", "value": "zSFIB" } ``` --- #### Message not sent {#message-not-sent-action} Find contacts who weren't sent a specific message. Example condition: _Find contacts who weren't sent a specific newsletter._ ```json { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "newsletter", "value": "z4Zje" } ``` Basic structure of condition: ```json { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "newsletter|autoresponder|splittest|automation", "value": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}" } ```
Value Description
{autoresponderId} To find {autoresponderId} use /v3/autoresponders
{newsletterId} To find {newsletterId} use /v3/newsletters
{splittestId} To find {splittestId} use /v3/newsletters?query[type]=splittest
{automationId} To find {automationId} use /v3/newsletters?query[type]=automation
You can find detailed information about **`"operatorType": "message_operator"`** here. Example conditions: _Find contacts who weren't sent a specific autoresponder email._ ```json { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "autoresponder", "value": "SY6kx" } ``` _Find contacts who weren't sent a specific newsletter._ ```json { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "newsletter", "value": "zhCwy" } ``` _Find contacts who weren't sent a specific splittest._ ```json { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "splittest", "value": "zSp9V" } ``` _Find contacts who weren't sent a specific automation message._ ```json { "conditionType": "not_sent", "operatorType": "message_operator", "operator": "automation", "value": "zSFIB" } ``` ### Geolocation {#create-geolocation-search-contacts} Search for contacts by geolocation. **Example condition** _Find contacts whose city name start with "new"._ ```json { "conditionType": "geo", "operatorType": "string_operator", "operator": "starts", "value": "New", "scope": "city" } ``` **Basic structure of condition** ```json { "conditionType": "geo", "operatorType": "string_operator", "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends", "value": "", "scope": "country|country_code|region|city|longitude|latitude|postal_code|dma_code" } ``` **Table of allowed fields and their values**
operatorType Allowed operators Allowed values
string_operator is, is_not, contains, not_contains, starts, ends, not_starts, not_ends <string>
You can find detailed information about **`"operatorType": "string_operator"`** here. ### GDPR {#create-gdpr-search-contacts} Search for contacts based on given or not given consents. **Basic structure of condition** ```json { "conditionType": "gdpr", "consentStatus": "given|not_given", "gdprFieldId": "{gdprFieldId}", "consentDate": { "operator": "anytime|dateFrom|dateTo", "date": "{utcDateFormat}" } } ``` Dependencies between `operator` field and `date` field:
operator date
anytime field date is prohibited
date_from, date_to Field date is required and have to be provided in format: {utcDateFormat}
Values description:
Value Description
{gdprFieldId} To find {gdprFieldId} use /v3/getGDPRFieldList
{utcDateFormat} UTC date format RFC3339, e.g. "2024-11-08".
Only for "operator": "date_from|date_to"
Examples: _Find contacts who give a consent `abc`._ ```json { "conditionType": "gdpr", "consentStatus": "given", "gdprFieldId": "abc", "consentDate": { "operator": "anytime" } } ``` _Find contacts who haven't given consent `abc` by 2023-12-31._ ```json { "conditionType": "gdpr", "consentStatus": "not_given", "gdprFieldId": "abc", "consentDate": { "operator": "date_to", "date": "2023-12-31" } } ``` ### Scoring {#create-scoring-search-contacts} Searching for contacts by score. **Example condition** _Find contacts whose score is lower than 5._ ```json { "conditionType": "score", "operatorType": "numeric_operator", "operator": "numeric_lt", "value": "5" } ``` **Basic structure of condition** ```json { "conditionType": "score", "operatorType": "numeric_operator|not_exists", "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq", "value": "" } ``` If `"operatorType": "not_exists"` is defined, fields `"operator"` and `"value"` are prohibited. **Table of allowed fields and their values**
operatorType Allowed operators Allowed values
numeric_operator numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq <integer>
not_exists   fields "operator" and "value" prohibited
You can find detailed information for **`"operatorType"`** equal to **`"numeric_operator"`** and **`"not_exists"`** here. **Example conditions** _Find contacts whose score is greater than or equal to 44._ ```json { "conditionType": "score", "operatorType": "numeric_operator", "operator": "numeric_gt_eq", "value": "44" } ``` _Find contacts who have no score._ ```json { "conditionType": "score", "operatorType": "not_exists" } ``` ### Engagement Score {#create-engagement-score-search-contacts} Searching for contacts by engagement score. **Example condition** _Find contacts whose engagement score is lower than 5._ ```json { "conditionType": "engagement_score", "operator": "numeric_lt", "value": "5" } ``` **Basic structure of condition** ```json { "conditionType": "engagement_score", "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq", "value": "" } ``` **Table of allowed fields and their values**
Allowed operators Allowed values
numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq <integer>
**Example conditions** _Find contacts whose engagement score is greater than or equal to 3._ ```json { "conditionType": "engagement_score", "operator": "numeric_gt_eq", "value": "3" } ``` ### Tags {#create-tags-search-contacts} Search for contacts by tags. **Example condition** ```json { "conditionType": "tag", "value": "BB", "operatorType": "exists", "operator": "exists" } ``` **Basic structure of condition** ```json { "conditionType": "tag", "value": "{tagId}", "operatorType": "exists", "operator": "exists|not_exists" } ```
Value Description
{tagId} Tag identifier can be fetched from /v3/tags
You can find detailed information about **`"operatorType": "exists"`** here. ### Ecommerce {#create-ecommerce-search-contacts} Searching for contacts by ecommerce parameters.
{conditionType} Description
ecommerce_number_of_purchases Searching for contacts by the number of purchases made.
ecommerce_total_spent Searching for contacts by total spent.
ecommerce_product_purchased Searching for contacts by product purchased.
ecommerce_brand_purchased Searching for contacts by brand purchased.
ecommerce_abandoned_cart Searching for contacts by abandoned cart.
--- #### ecommerce_number_of_purchases {#ecommerce-number-of-purchases-condition-type} Searching for contacts by the number of purchases made. Example condition: _Find contacts who bought 7 products in a specific store._ ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "all", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "7", "date": { "operator": "anytime" } } ``` Basic structure of condition: ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "all|{shopId}", "operatorType": "numeric_operator", "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq", "value": "", "date": { "operator": "anytime|today|yesterday|last_n_days|this_week|last_week|this_month|last_month|last_2_months|custom", "range": "{rangeUTCDateFormat}", "numberOfDays": "", "includeCurrentPeriod": "" } } ``` Table of allowed fields and their values:
Field Allowed operators Allowed values
operatorType numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq Field value <integer> is required.
date.operator anytime, today, yesterday, this_week, last_week, this_month, last_month, last_2_months No values required. Fields date.numberOfDays, date.includeCurrentPeriod, date.range are prohibited.
  last_n_days Fields date.numberOfDays <integer>, date.includeCurrentPeriod <boolean> are required. Field date.range is prohibited.
  custom Field date.range {rangeUTCDateFormat} is required. Fields date.numberOfDays, date.includeCurrentPeriod are prohibited.
Value Description
{shopId} Shop identifier can be fetched from /v3/shops
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "date": {"operator": "custom"}.
Example conditions: _Search all stores to find contacts who bought 7 products._ ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "all", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "7", "date": { "operator": "anytime" } } ``` _Find contacts who bought fewer than 5 products from a specific store._ ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "ZTo", "operatorType": "numeric_operator", "operator": "numeric_lt", "value": "5", "date": { "operator": "anytime" } } ``` _Search all stores to find contacts who bought 7 products on last 17 days excluding today._ ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "all", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "7", "date": { "operator": "last_n_days", "numberOfDays": "17", "includeCurrentPeriod": "false" } } ``` _Search all stores to find contacts who bought 7 products on last week._ ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "all", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "7", "date": { "operator": "last_week" } } ``` _Search all stores to find contacts who bought 7 products on custom date range._ ```json { "conditionType": "ecommerce_number_of_purchases", "scope": "all", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "7", "date": { "operator": "custom", "range": "2018-04-02/2018-04-23" } } ``` --- #### ecommerce_total_spent {#ecommerce-total-spent-condition-type} Search for contacts by total spent. Example condition: _Search all stores to find contacts who spent a total of 5.00 USD._ ```json { "conditionType": "ecommerce_total_spent", "scope": "all", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "5.00", "currency": "USD", "date": { "operator": "anytime" } } ``` Basic structure of condition: ```json { "conditionType": "ecommerce_total_spent", "scope": "all|{shopId}", "operatorType": "numeric_operator", "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq", "value": "", "currency": "{currencyCode}", "date": { "operator": "anytime|today|yesterday|last_n_days|this_week|last_week|this_month|last_month|last_2_months|custom", "range": "{rangeUTCDateFormat}", "numberOfDays": "", "includeCurrentPeriod": "" } } ``` Table of allowed fields and their values:
Field Allowed operators Allowed values
operatorType numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq Field value <integer> is required.
date.operator anytime, today, yesterday, this_week, last_week, this_month, last_month, last_2_months No values required. Fields date.numberOfDays, date.includeCurrentPeriod <boolean>, date.range are prohibited.
  last_n_days Fields date.numberOfDays <integer>, date.includeCurrentPeriod <boolean> are required. Field date.range is prohibited.
  custom Field date.range {rangeUTCDateFormat} is required. Fields date.numberOfDays, date.includeCurrentPeriod are prohibited.
Value Description
{shopId} Shop identifier can be fetched from /v3/shops
{currencyCode} Currency codes compatible with ISO 4217. List of currency codes listed here
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "date": {"operator": "custom"}.
Example conditions: _Search all stores to find contacts who spent a total of 5.00 USD._ ```json { "conditionType": "ecommerce_total_spent", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "5.00", "scope": "all", "currency": "USD", "date": { "operator": "anytime" } } ``` _Find contacts that spent a total of 8.00 EUR from a specific store._ ```json { "conditionType": "ecommerce_total_spent", "operatorType": "numeric_operator", "operator": "numeric_not_eq", "value": "8.00", "scope": "ZTo", "currency": "EUR", "date": { "operator": "anytime" } } ``` _Search all stores to find contacts who spent a total of 5.00 USD on last 25 days including today._ ```json { "conditionType": "ecommerce_total_spent", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "5.00", "scope": "all", "currency": "USD", "date": { "operator": "last_n_days", "numberOfDays": "25", "includeCurrentPeriod": "true" } } ``` _Search all stores to find contacts who spent a total of 5.00 USD on custom date range._ ```json { "conditionType": "ecommerce_total_spent", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "5.00", "scope": "all", "currency": "USD", "date": { "operator": "custom", "range": "2018-04-02/2018-04-23" } } ``` _Search all stores to find contacts who spent a total of 5.00 USD on last month._ ```json { "conditionType": "ecommerce_total_spent", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "5.00", "scope": "all", "currency": "USD", "date": { "operator": "last_month" } } ``` --- #### ecommerce_product_purchased {#ecommerce-product-purchased-condition-type} This condition type allows to search product purchased from (all shops)/(specified shop) for (any category)/(specified category) where (any product)/(specified product) (is)/(isn't) purchased (in time period)/(to specified date)/(from specified date). Example condition: _Find contacts who have purchased products in any category starting 2018-04-02._ ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all", "categoryScope": "all", "operatorType": "equal_operator", "operator": "is", "productScope": "all", "dateOperator": "date_from", "value": "2018-04-02" } ``` Basic structure of condition: ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all|{shopId}", "categoryScope": "all|{categoryId}", "operatorType": "equal_operator", "operator": "is|is_not", "productScope": "all|{productId}", "dateOperator": "all_time|date_to|date_from|today|yesterday|last_7_days|last_30_days|last_n_days|this_week|last_week|this_month|last_month|last_2_month|custom", "value": "{utcDateFormat}|{rangeUTCDateFormat}" } ``` Table of allowed fields and their values:
Field Allowed operators Allowed values
dateOperator date_to, date_from Field value {utcDateFormat} is required. Fields numberOfDays, includeCurrentPeriod are prohibited.
  all_time, today, yesterday, this_week, last_week, this_month, last_month, last_2_month No values required. Fields value, numberOfDays, includeCurrentPeriod are prohibited.
  last_n_days Fields numberOfDays <integer>, includeCurrentPeriod <boolean> are required. Field value is prohibited.
  last_7_days, last_30_days No values required. Fields value, numberOfDays are prohibited. Field includeCurrentPeriod <boolean> is optional.
  custom Field value {rangeUTCDateFormat} is required. Fields numberOfDays, includeCurrentPeriod are prohibited.
Value Description
{shopId} Shop identifier can be fetched from /v3/shops
{categoryId} Category identifier can be fetched from /v3/shops/{shopId}/categories
{productId} Product identifier can be fetched from /v3/shops/{shopId}/products
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "dateOperator": "date_to|date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "dateOperator": "custom".
For the specific **`"dateOperator": "last_n_days"`** structure of condition is extended by two parameters. ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all|{shopId}", "categoryScope": "all|{categoryId}", "operatorType": "equal_operator", "operator": "is|is_not", "productScope": "all|{productId}", "dateOperator": "last_n_days", "numberOfDays": "", "includeCurrentPeriod": "" } ``` For the specific **`"dateOperator": "last_7_days|last_30_days"`** structure of condition is extended by one parameter. ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all|{shopId}", "categoryScope": "all|{categoryId}", "operatorType": "equal_operator", "operator": "is|is_not", "productScope": "all|{productId}", "dateOperator": "last_7_days|last_30_days", "includeCurrentPeriod": "" } ``` Field **`"numberOfDays"`** required only for **`"dateOperator": "last_n_days"`**. Field **`"includeCurrentPeriod"`** required only for **`"dateOperator": "last_n_days"`**. Optional for **`"dateOperator": "last_7_days|last_30_days"`** Table of allowed fields and their values:
dateOperator allowed values
all_time, today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month, custom Field "numberOfDays" is prohibited.
last_n_days <integer>
Table of relation between value and includeCurrentPeriod:
dateOperator is includeCurrentPeriod allowed
all_time, today, yesterday, this_week, last_week, this_month, last_month, last_2_month Field "includeCurrentPeriod" is prohibited.
last_7_days, last_30_days, last_n_days <boolean>
Example conditions: ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all", "categoryScope": "all", "operatorType": "equal_operator", "operator": "is", "productScope": "all", "dateOperator": "all_time" } ``` ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all", "categoryScope": "all", "operatorType": "equal_operator", "operator": "is_not", "productScope": "P", "dateOperator": "all_time" } ``` ```json { "conditionType": "ecommerce_product_purchased", "categoryScope": "all", "productScope": "all", "operatorType": "equal_operator", "operator": "is", "shopScope": "ZTo", "dateOperator": "date_to", "value": "2018-05-07" } ``` ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "ZTo", "categoryScope": "P", "operatorType": "equal_operator", "operator": "is_not", "productScope": "all", "dateOperator": "custom", "value": "2018-05-01/2018-05-31" } ``` ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "ZTo", "categoryScope": "P", "operatorType": "equal_operator", "operator": "is_not", "productScope": "all", "dateOperator": "all_time" } ``` ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "ZTo", "categoryScope": "P", "operatorType": "equal_operator", "operator": "is_not", "productScope": "all", "dateOperator": "last_n_days", "numberOfDays": "30", "includeCurrentPeriod": "false" } ``` --- #### ecommerce_brand_purchased {#ecommerce-brand-purchased-condition-type} Search for contacts by brand purchased. Example condition: ```json { "conditionType": "ecommerce_brand_purchased", "scope": "ZTo", "operatorType": "equal_operator", "operator": "is", "value": "Vendor1" } ``` Basic structure of condition: ```json { "conditionType": "ecommerce_brand_purchased", "scope": "{shopId}", "operatorType": "equal_operator", "operator": "is|is_not", "value": "{vendorName}", } ```
Value Description
{shopId} Shop identifier can be fetched from /v3/shops
{vendorName} One of values from vendor field added to products /v3/shops/{shopId}/products
Example conditions: ```json { "conditionType": "ecommerce_brand_purchased", "scope": "ZTo", "operatorType": "equal_operator", "operator": "is", "value": "Vendor1" } ``` ```json { "conditionType": "ecommerce_brand_purchased", "scope": "ZTo", "operatorType": "equal_operator", "operator": "is_not", "value": "Vendor2" } ``` --- #### ecommerce_abandoned_cart {#ecommerce-abandoned-cart-condition-type} Find contacts who abandoned their cart. Example condition: ```json { "conditionType": "ecommerce_abandoned_cart", "shopScope": "all", "dateOperator": "date_from", "value": "2022-04-02", "cartValue": { "operator": "numeric_gt_eq", "value": "1", "currency": "USD", } } ``` Basic structure of condition: ```json { "conditionType": "ecommerce_abandoned_cart", "shopScope": "all|{shopId}", "dateOperator": "anytime|never||date_from|today|yesterday|this_week|last_week|this_month|last_month|last_n_days|custom", "value": "{utcDateFormat}|", "includeCurrentPeriod": "", "range": "{rangeUTCDateFormat}", "cartValue": { "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq", "value": "", "currency": "{currencyCode}" } } ``` Field **`"value"`** required only for **`"dateOperator": "date_from|last_n_days"`**, for others **`"dateOperator"`** it is prohibited. Field **`"includeCurrentPeriod"`** is optional and used only with **`"value": "last_n_days"`**, for others **`"dateOperator"`** it is prohibited. Field **`"range"`** required only for **`"value": "custom"`**, for others **`"dateOperator"`** it is prohibited. Table of allowed fields and their values:
Field Allowed operators Allowed values
dateOperator date_from {utcDateFormat}
  anytime, never, today, yesterday, this_week, last_week, this_month, last_month, custom Field "value" is prohibited.
  last_n_days <integer>
  custom {rangeUTCDateFormat}
Value Description
{shopId} Shop identifier can be fetched from /v3/shops
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for "dateOperator": "date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e."date_from/date_to" where date_from and date_to are in the UTC formatRFC3339. e.g. "2018-04-02/2018-04-23".
Only for "dateOperator": "custom".
{currencyCode} Currency codes compatible with ISO 4217. List of currency codes listed here
Example conditions: ```json { "conditionType": "ecommerce_abandoned_cart", "shopScope": "all", "dateOperator": "anytime", "cartValue": { "operator": "numeric_gt_eq", "value": "1", "currency": "USD", } } ``` ```json { "conditionType": "ecommerce_abandoned_cart", "shopScope": "all", "dateOperator": "date_from", "value": "2018-05-07", "cartValue": { "operator": "numeric_gt_eq", "value": "1", "currency": "USD" } } ``` ```json { "conditionType": "ecommerce_abandoned_cart", "shopScope": "ZTo", "dateOperator": "last_n_days", "value": 18, "includeCurrentPeriod": true, "cartValue": { "operator": "numeric_gt_eq", "value": "1", "currency": "USD", } } ``` ### SMS (Text messaging) {#create-sms-search-contacts} Searching for contacts using SMS parameters.
{conditionType} Description
sms_sent Find contacts who were sent a specific SMS.
sms_delivered Find contacts who received a specific SMS.
sms_link_clicked Find contacts who clicked a specific link.
sms_link_not_clicked Find contacts who didn't click a specific link.
--- #### sms_sent {#sms-sent-condition-type} Find contacts who were sent a specific SMS. Example condition: _Find contacts who were sent an SMS with an identifier ABc._ ```json { "conditionType": "sms_sent", "smsId": "ABc", "deliveryStatus": "any" } ``` _Find contacts who received an SMS with an identifier ABc._ ```json { "conditionType": "sms_sent", "smsId": "ABc", "deliveryStatus": "delivered" } ``` Basic structure of condition: ```json { "conditionType": "sms_sent", "smsId": "{smsId}", "deliveryStatus": "delivered|undelivered|any" } ```
Value Description
{smsId} Sms identifier can be fetched from /v3/sms
deliveryStatus Specifies the current status of delivery for a given SMS. This field allows you to filter contacts based on their delivery progress. You may omit this field or set `any` if the delivery status is not relevant to your search.
--- #### sms_link_clicked {#sms-link-clicked-condition-type} Find contacts who clicked a specific link from a specific SMS. Example condition: _Find contacts who clicked a link with an identifier `L` from an SMS with an identifier `ABc`._ ```json { "conditionType": "sms_link_clicked", "smsId": "ABc", "clickTrackId": "L" } ``` Basic structure of condition: ```json { "conditionType": "sms_link_clicked", "smsId": "{smsId}", "clickTrackId": "{clickTrackId}" } ```
Value Description
{smsId} SMS identifier can be fetched from /v3/sms
{clickTrackId} To get {clickTrackId}, fetch the message details from /v3/sms/{smsId} or use /v3/click-tracks
--- #### sms_link_not_clicked {#sms-link-not-clicked-condition-type} Find contacts who didn't click a specific link from a specific SMS. Example condition: _Find contacts who didn't click a link with an identifier L from an SMS with an identifier ABc._ ```json { "conditionType": "sms_link_not_clicked", "smsId": "ABc", "clickTrackId": "L" } ``` Basic structure of condition: ```json { "conditionType": "sms_link_not_clicked", "smsId": "{smsId}", "clickTrackId": "{clickTrackId}" } ```
Value Description
{smsId} SMS identifier can be fetched from /v3/sms
{clickTrackId} To get {clickTrackId}, fetch the message details from /v3/sms/{smsId} or use /v3/click-tracks
### Custom Events {#create-custom-events-search-contacts} Search for contacts by custom events. **Example conditions** _Find contacts for which the custom event with identifier `BB` not occurred anytime:_ ```json { "conditionType": "custom_event", "customEventId": "BB", "occurrence": "not_occurred", "dateOperator": "anytime" } ``` _Find contacts for which the custom event with identifier `BB` occurred yesterday:_ ```json { "conditionType": "custom_event", "customEventId": "BB", "occurrence": "occurred", "dateOperator": "yesterday" } ``` _Find contacts for which the custom event with identifier `BB` not occurred in last 2 months:_ ```json { "conditionType": "custom_event", "customEventId": "BB", "occurrence": "not_occurred", "dateOperator": "last_2_months" } ``` _Find contacts for which the custom event with identifier `BB` occurred after 2000-01-01_ ```json { "conditionType": "custom_event", "customEventId": "BB", "occurrence": "occurred", "dateOperator": "date_from", "date": "2000-01-01" } ``` _Find contacts for which the custom event with identifier `BB` occurred before 2000-01-01_ ```json { "conditionType": "custom_event", "customEventId": "BB", "occurrence": "occurred", "dateOperator": "date_to", "date": "2000-01-01" } ``` _Find contacts for which the custom event with identifier `BB` occurred between 2000-01-01 and 2000-01-31_ ```json { "conditionType": "custom_event", "customEventId": "BB", "occurrence": "occurred", "dateOperator": "custom", "date": "2000-01-01/2000-01-31" } ``` **Basic structure of condition** ```json { "conditionType": "custom_event", "customEventId": "{customEventId}", "occurrence": "occurred|not_occurred", "dateOperator": "anytime|date_to|date_from|custom|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_months", "date": "{utcDateFormat}|{rangeUTCDateFormat}" } ``` **Table of allowed `dateOperator` values:**
Field Allowed operators Allowed values
dateOperator date_to, date_from {utcDateFormat}
  anytime, today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month Field date is prohibited.
custom {rangeUTCDateFormat}
**Table of allowed data types:**
Value Description
{customEventId} Custom Event identifier can be fetched from /v3/custom-events
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10".
Only for"dateOperator": "date_to|date_from".
{rangeUTCDateFormat} ISO8601 format date interval, i.e."date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23".
Only for "dateOperator": "custom".
### Segment response {#search-contacts-response} **Basic structure of response:** ```json { "contactId": "{contactId}", "href": "https://api.getresponse.com/v3/contacts/{contactId}", "name": "{nameOfContact}", "email": "{emailOfContact}", "origin": "{origin}", "dayOfCycle": "{dayOfCycle}", "createdOn": "{createdOn}", "campaign": { "campaignId": "{campaignId}", "name": "{campaignName}", "href": "https://api.getresponse.com/v3/campaigns/{campaignId}" }, "score": "{score}", "reason": "{reason}", "deletedOn": "{deletedOn}" } ``` The response structure is compatible with /v3/contacts. ## Create a new segment {#create-search-contacts} This endpoint allows you to create a new segment. You first need to familiarize yourself with the basic concepts from [`/v3/search-contacts/contacts`](#get-all-contacts-from-search-contacts). **Example request** `/v3/search-contacts` ```json { "name": "custom test filter", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "logicOperator": "and", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "name", "operatorType": "string_operator", "operator": "contains", "value": "John" } ] } ] } ``` **Example of response** ```json { "searchContactId": "b3EkT", "name": "custom test filter", "createdOn": "2018-05-04T15:59:44+0000", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "logicOperator": "and", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "name", "operatorType": "string_operator", "operator": "contains", "value": "John" } ] } ], "href": "https://api.getresponse.com.agierszewski.u.c/v3/search-contacts/b3EkT" } ``` **Basic structure of request** ```json { "name": "{searchContactName}", "subscribersType": , "sectionLogicOperator": "{sectionLogicOperator}", "section": } ``` The structure of the request is almost the same as in [`/v3/search-contacts/contacts`](#get-all-contacts-from-search-contacts). This is different with the addition of a new "name" field that specifies the unique segment name.
Value Description Limitations
{searchContactName} Unique name of segment Expected string length between: 1 and 128
<subscribersType> An array with the following values:
"subscribed",
"undelivered",
"removed",
"unconfirmed"		 An array should contain only one element. Although validation allows for many elements (due to BC), only the first one will be taken into account
{sectionLogicOperator} Enum(or, and), match 'any' or 'all' of the following sections of described conditions  
<section-items> A collection of section-item describing the search conditions Up to 8 sections are allowed.
**Basic structure of response** ```json { "searchContactId": "{searchContactId}", "name": "{searchContactName}", "createdOn": "{createdOn}", "subscribersType": , "sectionLogicOperator": "{sectionLogicOperator}", "section": , "href": "https://api.getresponse.com/v3/search-contacts/{searchContactId}" } ```
Value Description
{searchContactId} Unique segment identifier
{createdOn} UTC date format RFC3339 i.e. "2018-04-19T14:37:02+0000"
<subscribersType> An array with the following values:
"subscribed",
"undelivered",
"removed",
"unconfirmed"
{searchContactName} Unique name of segment
{sectionLogicOperator} Enum(or, and), match 'any' or 'all' of the following sections of described conditions
<section-items> A collection of section-item describing the search conditions.
## Retrieve a collection of a short representation of a segment {#get-search-contacts} This endpoint allows you to retrieve a collection of a short representation of a segment. Every item represents a basic filter object. To learn more about the CONDITIONS used in the segment, go to section `/v3/search-contact/{searchContactId}` **Return** If the request is successful, returns HTTP 200 code with collection of segment items. **Example request** `/v3/search-contacts` **Example response** ```json [ { "searchContactId": "b3EGI", "name": "custom search contact filter 1", "createdOn": "2018-04-19T14:37:02+0000", "href": "https://api.getresponse.com/v3/search-contacts/b3EGI" }, { "searchContactId": "t8AO6", "name": "custom search contact filter 2", "createdOn": "2018-04-19T14:37:02+0000", "href": "https://api.getresponse.com/v3/search-contacts/t8AO6" } ] ``` **Basic structure of response** ```json { "searchContactId": "{searchContactId}", "name": "{searchContactName}", "createdOn": "{createdOn}", "href": "https://api.getresponse.com/v3/search-contacts/{searchContactId}" } ```
Value Description
{searchContactId} Unique segment (search-contact) identifier
{searchContactName} Unique name of search-contact
{createdOn} UTC date time format RFC3339, e.g. 2018-04-10T10:02:57+0000
You can limit the set of fields fetched by adding query parameters described here. ## Retrieve detailed information about a specific segment {#get-search-contacts-by-id} This endpoint retrieves more detailed information about a specific segment. It describes all conditions used for the segment specified. **Return** Returns the detailed description of segment with all defined conditions. **Request** `/v3/search-contacts/{searchContactId}` **Example response** ```json { "searchContactId": "b3Eta", "name": "custom test filter", "createdOn": "2018-04-23T12:07:15+0000", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "logicOperator": "and", "subscriberCycle": [ "receiving_autoresponder", "not_receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "name", "operatorType": "string_operator", "operator": "is", "value": "John" } ] } ], "href": "https://api.getresponse.com/v3/search-contacts/b3Eta" } ``` A detailed description of the results can be found at [`/v3/search-contacts`](#create-search-contacts). ## Update the existing search {#update-search-contacts} This endpoint allow to update the existing search.
Resource payload is the same as a segment without saving the search [`/v3/search-contacts/contacts`](#get-all-contacts-from-search-contacts). **Sample request** `/v3/search-contacts/b3Eta/` ```json { "name": "updated custom filter", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "logicOperator": "and", "subscriberCycle": [ "receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "custom", "scope": "pa3Ih", "operatorType": "string_operator_list", "operator": "is", "value": "Ireland" } ] } ] } ``` **Sample response** ```json { "searchContactId": "b3Eta", "name": "updated custom filter", "createdOn": "2018-04-27T12:55:05+0000", "subscribersType": [ "subscribed" ], "sectionLogicOperator": "or", "section": [ { "campaignIdsList": [ "tamqY" ], "logicOperator": "and", "subscriberCycle": [ "receiving_autoresponder" ], "subscriptionDate": "all_time", "conditions": [ { "conditionType": "custom", "scope": "pa3Ih", "operatorType": "string_operator_list", "operator": "is", "value": "Ireland" } ] } ], "href": "https://api.getresponse.com/v3/search-contacts/b3Eta" } ``` You can limit the set of fields fetched by adding query parameters described here. ## Delete a specified segment {#delete-search-contacts} This endpoint allow to delete a specified segment. **Example request** `/v3/search-contacts/b3Eta` **Example response** HTTP 204 resource deleted successfully ## Fetch all contacts that match the specified segment {#get-all-contacts-from-search-contacts-by-id} This endpoint allow to fetch all contact that match the specified segment. **Example request** `/v3/search-contacts/{searchContactId}/contacts` **Example response** ```json [ { "contactId": "jtLF5i", "href": "https://default_server/v3/contacts/jtLF5i", "name": "JohnSmith", "email": "johnsmith@example.com", "origin": "landing_page", "dayOfCycle": "108", "createdOn": "2018-01-15T13:30:42+0000", "campaign": { "campaignId": "tamqY", "name": "TestCampaign", "href": "https://api.getresponse.com/v3/campaigns/tamqY" }, "score": null, "reason": null, "deletedOn": null } ] ``` ## Add and update custom field values for all contacts that meet the search criteria {#custom-fields-search-contacts-by-id} The method allows adding and updating custom field values for all contacts that meet the search criteria. This method does not remove or overwrite custom fields with values from the request. **Returns status code** HTTP 202 **Example request** `/v3/search-contacts/b3Eta/custom-fields` ```json { "customFieldValues": [ { "customFieldId": "jHwRjh", "value": [ "white" ] } ] } ``` **Basic structure of request** ```json { "customFieldValues": [ { "customFieldId": "{customFieldId}", "value": [ "" ] } ] } ```
Value Description
{customFieldId} Custom field identifier. To find {customFieldId} use /v3/custom-fields.
## Appendix A - full list of operator types {#appendix-a} Not every "operator" value can be used for a given condition. A full list of available operators for the condition is given in the description of the condition. - [`string_operator`](#appendix-a-string-operator) - [`string_operator_list`](#appendix-a-string-operator-list) - [`date_operator`](#appendix-a-date-operator) - [`numeric_operator`](#appendix-a-numeric-operator) - [`message_operator`](#appendix-a-message-operator) - [`exists`](#appendix-a-exists) - [`not_exists`](#appendix-a-not-exists) - [`complex_message_operator`](#appendix-a-complex-message-operator) - [`equal_operator`](#appendix-a-equal-operator) ### `"string_operator"` {#appendix-a-string-operator} This `"operatorType"` allows to search for a string or a substring. **Example condition** ```json { "conditionType": "name", "operatorType": "string_operator", "operator": "contains", "value": "John" } ``` **Basic structure of condition** ```json { ..., "operatorType": "string_operator", "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends|assigned|not_assigned", "value": "" } ``` Where `` is any string **Table of relation between `operator` and `value` field**
Value of field operator Is field value required? Value of field value Additional information
is
is_not
contains
not_contains
starts
ends
not_starts
not_ends		 Required <string> This operator allows you to search for a string, substring
assigned
not_assigned		 Prohibited   Available only for custom field condition ("conditionType": "custom")
**Descriptions of possible values of field `"operator"`**
Value of field operator Description
is Is the same as "value"
is_not Is not the same as "value"
contains Contains "value" as substring,
not_contains Not contains "value" as substring
starts "value" is the beginning of the string
ends "value" is the end of the string
not_starts "value" is not the beginning of the string
not_ends "value" is not the end of the string
assigned  
not_assigned  
**Example conditions** ```json { "conditionType": "custom", "scope": "pa3Ui", "operatorType": "string_operator", "operator": "starts", "value": "new" } ``` ```json { "conditionType": "custom", "scope": "pa37y", "operatorType": "string_operator_list", "operator": "assigned" } ``` ### `"string_operator_list"` {#appendix-a-string-operator-list} The operator allows searching for a defined collection. `"string_operator_list"` can be used only in custom field condition (**`"conditionType": "custom"`**) **Example condition** _Find all contacts with the custom field "country" set to "Canada"._ ```json { "conditionType": "custom", "scope": "pa3Ih", "operatorType": "string_operator_list", "operator": "is", "value": "Canada" } ``` **Basic structure of condition** ```json { "operatorType": "string_operator_list", "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends|assigned|not_assigned", "value": "" } ``` Where `` is any string **Table of relation between `operator` and `value` field**
Value of field operator Is field value required? Value of field value Additional information
is
is_not
contains
not_contains
starts
ends
not_starts
not_ends		 Required <string> This operator allows you to search for a string, substring
assigned,
not_assigned		 Prohibited   Available only for custom field condition ("conditionType": "custom")
**Example conditions** _Find all contacts with the custom field "age" set to "18-29"._ ```json { "conditionType": "custom", "scope": "pa37y", "operatorType": "string_operator_list", "operator": "is", "value": "18-29" } ``` _Find all contacts with the custom field "country" set to "Canada"._ ```json { "conditionType": "custom", "scope": "pa3Ih", "operatorType": "string_operator_list", "operator": "is", "value": "Canada" } ``` ### `"date_operator"` {#appendix-a-date-operator} The operator allows searching by date. **Example condition** _Find contacts who were sent an email message till 2018-05-06._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "date_to", "value": "2018-05-06" } ``` **Basic structure of condition** ```json { ..., "operatorType": "date_operator", "operator": "date_to|date_from|specific_date|custom", "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}" } ``` **Table of relation between `operator` and `value` field**
Value of field operator Is field value required? Value of field value Additional information
date_to,
date_from		 Required {utcDateFormat} UTC date format RFC3339 e.g.
specific_date Required one of the following values:
today,
yesterday,
last_7_days,
last_30_days,
this_week,
last_week,
this_month,
last_month,
last_2_month		 {rangeUTCDateFormat} is string in form of "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23"
custom Required {rangeUTCDateFormat} {rangeUTCDateFormat} is string ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23"
**Example conditions** _Find contacts who have been sent an email within the last seven days._ ```json { "conditionType": "last_send_date", "operatorType": "date_operator", "operator": "specific_date", "value": "last_7_days" } ``` _Find all contacts with custom field "birthday" set to "between 1970-01-01 and 1979-12-31"._ ```json { "conditionType": "custom", "scope": "pa3Lo", "operatorType": "date_operator", "operator": "custom", "value": "1970-01-01/1979-12-31" } ``` ### `"numeric_operator"` {#appendix-a-numeric-operator} The operator allows searching by numeric fields. **Example condition** _Find contacts which are on a specific day in an autoresponder cycle._ ```json { "conditionType": "phase", "operatorType": "numeric_operator", "operator": "numeric_eq", "value": "6" } ``` **Basic structure of condition** ```json { ..., "operatorType": "numeric_operator", "operator": "numeric_lt|numeric_gr|numeric_eq|numeric_not_eq|numeric_not_eq|numeric_lt_eq|numeric_gr_eq|assigned|not_assigned", "value": "" } ``` **Table of relation between `operator` and `value` field**
Value of field operator Is field value required? Value of field value
numeric_lt is less than
numeric_gt is greater than
numeric_eq is equal to
numeric_not_eq is not equal to
numeric_lt_eq is less than or equal to
numeric_gt_eq is greater than or equal to		 Required <number>
assigned
not_assigned		 Prohibited  
### `"message_operator"` {#appendix-a-message-operator} The operator allows searching by type of a message. **Example condition** _Find contacts who opened a specific message._ ```json { "conditionType": "opened", "operatorType": "message_operator", "operator": "autoresponder", "value": "SGNLr" } ``` **Basic structure of condition** ```json { ..., "operatorType": "message_operator", "operator": "autoresponder", "value": "{autoresponderId}", "clickTrackId": "all|{clickTrackId}" } ``` **Table of relation between `operator` and `value` field**
Value of field operator Value of field value Additional information
newsletter {newsletterId} To find {newsletterId} use /v3/newsletters
autoresponder {autoresponderId} To find {autoresponderId} use /v3/autoresponders
splittest {splittestId} To find {splittestId} use /v3/newsletters?query[type]=splittest
automation {workflowId} To find {workflowId} use /v3/newsletters?query[type]=automation
**Information about placeholders**
Placeholder Description
{autoresponderId} To find {autoresponderId} use /v3/autoresponders
{newsletterId} To find {newsletterId} use /v3/newsletters
{splittestId} To find {splittestId} use /v3/newsletters?query[type]=splittest
{automationId} To find {automationId} use /v3/newsletters?query[type]=automation
{clickTrackId} To find {clickTrackId} fetch message details. i.e. /v3/newsletter/{newsletterId} or use /v3/click-tracks
**Example conditions** _Find contacts who clicked any link in a specific newsletter._ ```json { "conditionType": "clicked", "operatorType": "message_operator", "operator": "newsletter", "scope": "zlrzy", "clickTrackId": "all" } ``` _Find contacts who were sent a specific splittest._ ```json { "conditionType": "sent", "operatorType": "message_operator", "operator": "splittest", "value": "zSp9V" } ``` ### `"exists"` {#appendix-a-exists} The operator allows verifying whether or not the property you are looking for exists. **Example condition** ```json { "conditionType": "tag", "value": "BB", "operatorType": "exists", "operator": "exists" } ``` **Basic structure of condition** ```json { ..., "operatorType": "exists", "operator": "exists| not_exists", "value": "{tagId}" } ```
Value of field operator Is field value required? Value of field value Additional information
exists
not_exists		 For tags required.
For scoring prohibited.		 {tagId} To find {tagId} use /v3/tags
### `"not_exists"` {#appendix-a-not-exists} _Find contacts who dont have a score._ ```json { "conditionType": "score", "operatorType": "not_exists" } ``` ### `"complex_message_operator"` {#appendix-a-complex-message-operator} **Example condition** ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "autoresponder", "dateOperator": "never" } ``` **Basic structure of condition** ```json { ..., "operatorType": "complex_message_operator", "operator": "all|autoresponder|newsletter|splittest|automation", "scope": "{autoresponderId}|{newsletterId}|{splittestId}|{automationId}", "dateOperator": "date_from|never|today|yesterday|last_7_days|last_30_days|this_week|this_month", "value": "{utcDateFormat}", "clickTrackId": "all|{clickTrackId}" } ``` Required fields: - `operator` - `scope` - `dateOperator` - `value` - required only if `dateOperator` is `date_from`, please see table below - `clickTrackId` - required only if `scope` is not `all`
Value of field dateOperator Is field value required? Value of field value
date_from Required "{utcDateFormat}"
never, today, yesterday, last_7_days, last_30_days, this_week, this_month, last_month Prohibited  
**Fields description**
Field Value Description
{utcDateFormat} UTC date format RFC3339, e.g. "2018-04-10". Field "customDate" is required only for "subscriptionDate": "custom".
{autoresponderId} <hash> Autoresponder identifier. To find {autoresponderId} use /v3/autoresponders
{newsletterId} <hash> Newsletter identifier. To find {newsletterId} use /v3/newsletters
{splittestId} <hash> Splittest identifier. To find {splittestId} use /v3/newsletters?query[type]=splittests
{automationId} <hash> To find {automationId} use /v3/newsletters?query[type]=automation
{clickTrackId} <hash> To find {clickTrackId} fetch message details. i.e. /v3/newsletter/{newsletterId} or use /v3/click-tracks
**Example conditions** _Find contacts who haven't opened any newsletters for the last 7 days._ ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "newsletter", "dateOperator": "last_7_days", "scope": "all" } ``` _Find contacts who haven't opened a specific newsletter today._ ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "newsletter", "dateOperator": "today", "scope": "z4Zje" } ``` _Find contacts who haven't opened a specific newsletter today._ ```json { "conditionType": "not_opened", "operatorType": "complex_message_operator", "operator": "newsletter", "dateOperator": "today", "scope": "z4Zje" } ``` _Find contacts who haven't clicked a specific link in a specific splittest in the last 30 days ._ ```json { "conditionType": "not_clicked", "operatorType": "complex_message_operator", "operator": "splittest", "dateOperator": "last_30_days", "scope": "zSp9V", "clickTrackId": "PPxiOW" } ``` ### `"equal_operator"` {#appendix-a-equal-operator} **Example condition** _Find contacts who have purchased products of any category from 2018-04-02._ ```json { "conditionType": "ecommerce_product_purchased", "shopScope": "all", "categoryScope": "all", "operatorType": "equal_operator", "operator": "is", "productScope": "all", "dateOperator": "date_from", "value": "2018-04-02" } ``` **Basic structure of condition** ```json { ..., "operatorType": "equal_operator", "operator": "is|is_not", "value": "",5 ... } ``` ## Appendix B - list of currencies {#appendix-b} More information can be found at ISO 4217.
Currency ISO 4217 Currency ISO 4217 Currency ISO 4217
ADB Unit of Account XUA Guinean Franc GNF Pula BWP
Afghani AFN Guyana Dollar GYD Qatari Rial QAR
Algerian Dinar DZD Hong Kong Dollar HKD Quetzal GTQ
Argentine Peso ARS Hryvnia UAH Rand ZAR
Armenian Dram AMD Iceland Krona ISK Rial Omani OMR
Aruban Florin AWG Indian Rupee INR Riel KHR
Australian Dollar AUD Iranian Rial IRR Romanian Leu RON
Azerbaijan Manat AZN Iraqi Dinar IQD Rufiyaa MVR
Bahamian Dollar BSD Jamaican Dollar JMD Rupiah IDR
Bahraini Dinar BHD Jordanian Dinar JOD Russian Ruble RUB
Baht THB Kenyan Shilling KES Rwanda Franc RWF
Balboa PAB Kina PGK Saint Helena Pound SHP
Barbados Dollar BBD Kuna HRK Saudi Riyal SAR
Belarusian Ruble BYN Kuwaiti Dinar KWD SDR (Special Drawing Right) XDR
Belize Dollar BZD Kwanza AOA Serbian Dinar RSD
Bermudian Dollar BMD Kyat MMK Seychelles Rupee SCR
Bolívar VEF Lao Kip LAK Silver XAG
Boliviano BOB Lari GEL Singapore Dollar SGD
Brazilian Real BRL Lebanese Pound LBP Sol PEN
Brunei Dollar BND Lek ALL Solomon Islands Dollar SBD
Bulgarian Lev BGN Lempira HNL Som KGS
Burundi Franc BIF Leone SLL Somali Shilling SOS
Cabo Verde Escudo CVE Liberian Dollar LRD Somoni TJS
Canadian Dollar CAD Libyan Dinar LYD South Sudanese Pound SSP
Cayman Islands Dollar KYD Lilangeni SZL Sri Lanka Rupee LKR
CFA Franc BCEAO XOF Loti LSL Sucre XSU
CFA Franc BEAC XAF Malagasy Ariary MGA Sudanese Pound SDG
CFP Franc XPF Malawi Kwacha MWK Surinam Dollar SRD
Chilean Peso CLP Malaysian Ringgit MYR Swedish Krona SEK
Colombian Peso COP Mauritius Rupee MUR Swiss Franc CHF
Comorian Franc KMF Mexican Peso MXN Syrian Pound SYP
Congolese Franc CDF Mexican Unidad de Inversion (UDI) MXV Taka BDT
Convertible Mark BAM Moldovan Leu MDL Tala WST
Cordoba Oro NIO Moroccan Dirham MAD Tanzanian Shilling TZS
Costa Rican Colon CRC Mozambique Metical MZN Tenge KZT
Cuban Peso CUP Mvdol BOV Trinidad and Tobago Dollar TTD
Czech Koruna CZK Naira NGN Tugrik MNT
Dalasi GMD Nakfa ERN Tunisian Dinar TND
Danish Krone DKK Namibia Dollar NAD Turkish Lira TRY
Denar MKD Nepalese Rupee NPR Turkmenistan New Manat TMT
Djibouti Franc DJF Netherlands Antillean Guilder ANG UAE Dirham AED
Dobra STN New Israeli Sheqel ILS Uganda Shilling UGX
Dominican Peso DOP New Taiwan Dollar TWD Unidad de Fomento CLF
Dong VND New Zealand Dollar NZD Unidad de Valor Real COU
East Caribbean Dollar XCD Ngultrum BTN Uruguay Peso en Unidades Indexadas (URUIURUI) UYI
Egyptian Pound EGP North Korean Won KPW US Dollar USD
El Salvador Colon SVC Norwegian Krone NOK Uzbekistan Sum UZS
Ethiopian Birr ETB Ouguiya MRU Vatu VUV
Euro EUR Pa’anga TOP WIR Euro CHE
Falkland Islands Pound FKP Pakistan Rupee PKR WIR Franc CHW
Fiji Dollar FJD Palladium XPD Won KRW
Forint HUF Pataca MOP Yemeni Rial YER
Ghana Cedi GHS Peso Convertible CUC Yen JPY
Gibraltar Pound GIP Peso Uruguayo UYU Yuan Renminbi CNY
Gold XAU Philippine Piso PHP Zambian Kwacha ZMW
Gourde HTG Platinum XPT Zimbabwe Dollar ZWL
Guarani PYG Pound Sterling GBP Zloty PLN
## Appendix C - API requests query parameters {#appendix-c} There are optional parameters to control which data appears in the response.
Field name Field type Field description
query hash Used to search only resources that meet the criteria. You can specify multiple parameters. Then, the AND logic is applied. Available search parameters: name=*, createdOn[from]=Y-m-d, createdOn[to]=Y-m-d, i.e. ?query[name]=my+custom+filer&query[createdOn][from]=2018-04-01&query[createdOn][to]=2018-04-11
fields string List of fields that should be returned. Id is always returned. Fields should be separated by comma. Available field names depends on request: name, createdOn, href. i.e.: ?fields=name,createdOn
sort hash Enable sorting using specified field (set as a key) and order (set as a value). You can specify multiple fields to sort by. Available keys name=asc|desc and createdOn=asc|desc. i.e: ?sort[name]=desc&createdOn=asc
page integer Specify which page of results should return.
perPage integer Specify how many results per page should be returned. The maximum allowed number of results is 1000. Up to 8 conditions are allowed.
Examples of using query parameters - `/v3/search-contacts/?query[createdOn][from]=2018-04-01&query[createdOn][to]=2018-04-11&perPage=100&page=1&sort[name]=desc` - `/v3/search-contacts/?query[name]=my+custom+filer&sort[name]=desc` - `/v3/search-contacts/?query[createdOn][from]=2018-04-01&perPage=100&page=1&sort[name]=desc` - `/v3/search-contacts/?query[name]=my+custom+filer&query[createdOn][from]=2018-04-01&query[createdOn][to]=2018-04-11&fields=name,createdOn&perPage=100&page=1&sort[name]=desc` - `/v3/search-contacts/?fields=name,createdOn&perPage=100&page=1` - `/v3/search-contacts/b3Eta/contacts/?fields=name,email` --- # GetResponse and GetResponse MAX API - differences The GetResponse application uses two environments: `GetResponse` and `GetResponse MAX`. GetResponse MAX is a platform for enterprise type of businesses seeking scalable, high-performance solutions. There are some differences between those two environments, including in API. ## How to start with API You should first [create your `GetResponse` account](https://www.getresponse.com/start-free-trial). After you’ve created the account, you have access to the `API key` generating [function](https://app.getresponse.com/api?_gl=1*ge3qfs*_gcl_au*MjAyNDc0NjEyOS4xNzE3NzU0Nzkx*_ga*MTcxNzg1NTEyMC4xNjkzOTAzNDQ5*_ga_EQ6LD9QEJB*MTcxODEwMTc5MC44Ny4xLjE3MTgxMDE4MDEuNDkuMC4zMjI1NTgwNTE.*_ga_MWJQ4HH5SL*MTcxODEwMTc5MC44Ny4xLjE3MTgxMDE4MDEuNDkuMC4w&_ga=2.136054769.1169029903.1718022532-1717855120.1693903449), and other settings in your Panel. Depending on your package or add-ons, you can set `User` accounts. Every `User` can have their separate `API key`. `Users` have access to the account’s functions, though the account owner (admin) can restrict their access. In `GetResponse MAX,` the `Account Owner` can create `Accounts`. Please note that `Accounts` are completely separate, with their own campaigns (lists), messages etc. You can’t access one `Account's` data from another `Account`. Within an `Account,` you can add `Users`, with the same rules and permissions as in the `GetResponse' 'Users` feature. Note: For API purposes, create a `User` separate from the `Account` space and don’t assign multiple `Accounts` to this `User`. When you become a `GetResponse MAX` customer, you work with a dedicated Account Manager. Please don’t hesitate to ask our experts for advice. ## API Endpoint API endpoint (or base URL) is always the same for **GetResponse** users: `https://api.getresponse.com/v3` `v3` is the current version of our API. **GetResponse MAX platform** For the GetResponse MAX platform, the user’s endpoint is different. There are two different URLs, and any GetResponse MAX user who wants to connect to our API should contact their Account Manager to confirm which URL they should use. Note the **getresponse360** part of the URL. * `https://api3.getresponse360.pl/v3` * `https://api3.getresponse360.com/v3` ## Authentication **GetResponse MAX** customers have to add the `X-Domain` to **all** request headers. For example: ```bash X-Domain: example.com ``` Please note that the header must only contain the domain name, without the protocol identifier (http:// or https://). Please refer to the [Authentication](../authentication.md) reference for details. ### OAuth2 There are some differences when authenticating **GetResponse MAX** users: * the application must redirect to a page in the client’s custom domain, for example: `https://custom-domain.getresponse360.com/oauth2_authorize.html` * token requests have to be sent to one of the **GetResponse MAX** APIv3 endpoints (depending on the client’s environment), * token requests have to include an X-Domain header, * the application has to be registered in a **GetResponse MAX** account within the same environment. Please refer to [Using OAuth 2.0](../authentication/oauth2.md) for details.