# MailerLite CLI (/cli) A command-line interface for the MailerLite API. Manage subscribers, campaigns, automations, groups, forms, e-commerce, and more — all from your terminal. The CLI also includes an interactive TUI dashboard for browsing your MailerLite data in real time. [GitHub Repository](https://github.com/mailerlite/mailerlite-cli) ## Installation [#installation] ### Homebrew (macOS) [#homebrew-macos] ```bash brew install --cask mailerlite/tap/mailerlite ``` ### GitHub Releases [#github-releases] Download pre-built binaries for Linux, macOS, and Windows from the [releases page](https://github.com/mailerlite/mailerlite-cli/releases). ### Go install [#go-install] ```bash go install github.com/mailerlite/mailerlite-cli@latest ``` ### From source [#from-source] Requires Go 1.25+. ```bash git clone https://github.com/mailerlite/mailerlite-cli.git cd mailerlite-cli go build -o mailerlite . ``` Move the binary to somewhere on your `$PATH`: ```bash sudo mv mailerlite /usr/local/bin/ ``` ### Nix [#nix] Run directly without installing: ```bash nix run git+ssh://git@github.com/mailerlite/mailerlite-cli.git ``` Or install into your profile: ```bash nix profile install git+ssh://git@github.com/mailerlite/mailerlite-cli.git ``` ## Authentication [#authentication] The CLI supports two authentication methods: **OAuth** (recommended) and **API token**. ### OAuth (recommended) [#oauth-recommended] ```bash mailerlite auth login ``` This opens your browser to authorize the CLI with your MailerLite account. OAuth tokens are automatically refreshed when they expire. ### API Token [#api-token] ```bash mailerlite auth login --method token ``` You'll be prompted to enter your MailerLite API token. You can generate one from your [MailerLite dashboard](https://dashboard.mailerlite.com/integrations/api). ### Environment variable [#environment-variable] You can also set the API token via environment variable: ```bash export MAILERLITE_API_TOKEN="your_token_here" ``` ### Multiple profiles [#multiple-profiles] Manage multiple profiles for different accounts or environments: ```bash # Add profiles mailerlite profile add staging mailerlite profile add production # List profiles mailerlite profile list # Switch active profile mailerlite profile switch staging # Use a specific profile for one command mailerlite subscriber list --profile production ``` ### Multiple accounts [#multiple-accounts] If your OAuth credentials have access to multiple MailerLite accounts: ```bash # List accounts mailerlite account list # Switch active account mailerlite account switch ``` ### Auth status and logout [#auth-status-and-logout] ```bash # Check auth status mailerlite auth status # Log out mailerlite auth logout ``` ## Global flags [#global-flags] Every command supports these flags: | Flag | Description | | ------------------ | ------------------------------------------- | | `--json` | Output raw JSON instead of formatted tables | | `--verbose`, `-v` | Print HTTP request and response details | | `--profile ` | Use a specific auth profile | | `--yes`, `-y` | Skip confirmation prompts | | `--help`, `-h` | Show help for any command | ## Commands [#commands] ### Subscribers [#subscribers] ```bash # List subscribers mailerlite subscriber list mailerlite subscriber list --limit 50 --status active # Filter by email mailerlite subscriber list --email user@example.com # Get subscriber count mailerlite subscriber count # Get subscriber details (by ID or email) mailerlite subscriber get # Create or update a subscriber mailerlite subscriber upsert \ --email "user@example.com" \ --status active \ --groups "group1_id,group2_id" \ --fields '{"name":"John","company":"Acme"}' # Update a subscriber mailerlite subscriber update --status unsubscribed # Delete a subscriber mailerlite subscriber delete # Forget a subscriber (GDPR) mailerlite subscriber forget ``` ### Groups [#groups] ```bash # List groups mailerlite group list mailerlite group list --limit 50 --sort name # Create a group mailerlite group create --name "Newsletter" # Update a group mailerlite group update --name "Weekly Newsletter" # Delete a group mailerlite group delete # List subscribers in a group mailerlite group subscribers # Assign / unassign a subscriber mailerlite group assign mailerlite group unassign ``` ### Campaigns [#campaigns] ```bash # List campaigns mailerlite campaign list mailerlite campaign list --status sent --type regular # Get campaign details mailerlite campaign get # Create a campaign mailerlite campaign create \ --name "Welcome Campaign" \ --type regular \ --subject "Welcome!" \ --from "sender@yourdomain.com" \ --from-name "Sender Name" \ --content "

Hello

" \ --groups "group_id" # Update a campaign mailerlite campaign update --subject "Updated Subject" # Schedule a campaign mailerlite campaign schedule \ --delivery scheduled \ --date 2026-03-01 \ --hours 10 \ --minutes 0 # Cancel a campaign mailerlite campaign cancel # List campaign subscriber activity mailerlite campaign subscribers # List available campaign languages mailerlite campaign languages # Delete a campaign mailerlite campaign delete ``` ### Automations [#automations] ```bash # List automations mailerlite automation list mailerlite automation list --enabled true # Get automation details mailerlite automation get # List automation subscriber activity mailerlite automation subscribers ``` ### Forms [#forms] ```bash # List forms mailerlite form list mailerlite form list --type popup --sort name # Get form details mailerlite form get # Update a form mailerlite form update --name "Updated Form" # Delete a form mailerlite form delete # List form subscribers mailerlite form subscribers ``` ### Fields [#fields] ```bash # List subscriber fields mailerlite field list # Create a field mailerlite field create --name "Company" --type text # Update a field mailerlite field update --name "Organization" # Delete a field mailerlite field delete ``` ### Segments [#segments] ```bash # List segments mailerlite segment list # Update a segment mailerlite segment update --name "VIP Customers" # Delete a segment mailerlite segment delete # List subscribers in a segment mailerlite segment subscribers ``` ### Webhooks [#webhooks] ```bash # List webhooks mailerlite webhook list # Create a webhook mailerlite webhook create \ --name "My Webhook" \ --url "https://example.com/webhook" \ --events "subscriber.created,campaign.sent" \ --enabled # Get webhook details mailerlite webhook get # Update a webhook mailerlite webhook update --name "Updated Webhook" # Delete a webhook mailerlite webhook delete ``` #### Webhook events [#webhook-events] | Event | Description | | --------------------------------- | -------------------------------------------- | | `subscriber.created` | A new subscriber was added | | `subscriber.updated` | A subscriber was updated | | `subscriber.unsubscribed` | A subscriber unsubscribed | | `subscriber.added_to_group` | A subscriber was added to a group | | `subscriber.removed_from_group` | A subscriber was removed from a group | | `subscriber.bounced` | A subscriber's email bounced | | `subscriber.automation_triggered` | An automation was triggered for a subscriber | | `subscriber.automation_completed` | An automation completed for a subscriber | | `campaign.sent` | A campaign was sent | | `campaign.draft_created` | A campaign draft was created | ### Timezones [#timezones] ```bash # List available timezones mailerlite timezone list ``` ### E-Commerce: Shops [#e-commerce-shops] ```bash # List shops mailerlite shop list # Get shop details mailerlite shop get # Create a shop mailerlite shop create --name "My Store" --url "https://mystore.com" # Update a shop mailerlite shop update --name "Updated Store" # Delete a shop mailerlite shop delete # Get shop count mailerlite shop count ``` ### E-Commerce: Products [#e-commerce-products] All product commands require `--shop`. ```bash # List products mailerlite product list --shop # Get product details mailerlite product get --shop # Create a product mailerlite product create --shop \ --name "T-Shirt" \ --price 29.99 \ --url "https://mystore.com/tshirt" \ --description "A nice t-shirt" # Update a product mailerlite product update --shop --price 24.99 # Delete a product mailerlite product delete --shop # Get product count mailerlite product count --shop ``` ### E-Commerce: Categories [#e-commerce-categories] All category commands require `--shop`. ```bash # List categories mailerlite category list --shop # Get category details mailerlite category get --shop # Create a category mailerlite category create --shop --name "Apparel" # Update a category mailerlite category update --shop --name "Clothing" # Delete a category mailerlite category delete --shop # Get category count mailerlite category count --shop # List products in a category mailerlite category products --shop # Assign / unassign a product mailerlite category assign-product \ --shop --product mailerlite category unassign-product \ --shop --product ``` ### E-Commerce: Customers [#e-commerce-customers] All customer commands require `--shop`. ```bash # List customers mailerlite customer list --shop # Get customer details mailerlite customer get --shop # Create a customer mailerlite customer create --shop \ --email "customer@example.com" \ --first-name "John" \ --last-name "Doe" # Update a customer mailerlite customer update --shop --first-name "Jane" # Delete a customer mailerlite customer delete --shop # Get customer count mailerlite customer count --shop ``` ### E-Commerce: Orders [#e-commerce-orders] All order commands require `--shop`. ```bash # List orders mailerlite order list --shop # Get order details mailerlite order get --shop # Create an order mailerlite order create --shop \ --customer \ --status complete \ --total 59.98 \ --currency USD \ --items '[{"product_id":"prod1","quantity":2,"price":29.99}]' # Update an order mailerlite order update --shop --status complete # Delete an order mailerlite order delete --shop # Get order count mailerlite order count --shop ``` ### E-Commerce: Carts [#e-commerce-carts] All cart commands require `--shop`. ```bash # List carts mailerlite cart list --shop # Get cart details mailerlite cart get --shop # Update a cart mailerlite cart update --shop --currency EUR # Get cart count mailerlite cart count --shop ``` ### E-Commerce: Cart Items [#e-commerce-cart-items] All cart-item commands require `--shop` and `--cart`. ```bash # List cart items mailerlite cart-item list --shop --cart # Get cart item details mailerlite cart-item get --shop --cart # Add an item to a cart mailerlite cart-item create --shop --cart \ --product \ --quantity 2 \ --price 29.99 # Update a cart item mailerlite cart-item update \ --shop --cart --quantity 3 # Delete a cart item mailerlite cart-item delete --shop --cart # Get cart item count mailerlite cart-item count --shop --cart ``` ### E-Commerce: Bulk Import [#e-commerce-bulk-import] ```bash # Import categories from JSON file mailerlite import categories --shop --file categories.json # Import products from JSON file mailerlite import products --shop --file products.json # Import orders from JSON file mailerlite import orders --shop --file orders.json ``` ### Interactive dashboard [#interactive-dashboard] Launch the TUI dashboard for a visual overview of your MailerLite account: ```bash mailerlite dashboard ``` The dashboard provides a lazygit-style interface with sidebar navigation between subscribers, campaigns, automations, groups, and forms. Use vim-style keybindings (`j`/`k` to navigate, `Enter` to select). Press `?` for help or `q` to quit. ## JSON output [#json-output] Add `--json` to any command to get raw JSON output, useful for scripting and piping to tools like `jq`: ```bash # Pipe to jq mailerlite subscriber list --json | jq '.[].email' # Extract an ID mailerlite group create --name "Test" --json | jq -r '.id' ``` The CLI also respects the `NO_COLOR` environment variable to disable colored output. ## Shell completion [#shell-completion] Generate shell completions for your shell: ```bash # Bash source <(mailerlite completion bash) # Zsh mailerlite completion zsh > "${fpath[1]}/_mailerlite" # Fish mailerlite completion fish | source # PowerShell mailerlite completion powershell | Out-String | Invoke-Expression ``` # Getting started (/getting-started) ## MailerLite API [#mailerlite-api] MailerLite API is RESTful, fully-featured, and easy to integrate with. You can use your favorite HTTP/REST library that is available for your programming language to make HTTP calls. You must send JSON payloads in your requests and expect to get JSON responses. Don't forget to add these headers to each and every request. ```http Content-Type: application/json Accept: application/json ``` Use the following base URL for all API endpoints: ``` https://connect.mailerlite.com/api ``` ## SDK [#sdk] MailerLite supports this list of official libraries for your favorite programming languages. This is the easiest way to integrate MailerLite with your application. * [MailerLite PHP](https://github.com/mailerlite/mailerlite-php) * [MailerLite Go](https://github.com/mailerlite/mailerlite-go) * [MailerLite Node.js](https://github.com/mailerlite/mailerlite-nodejs) * [MailerLite Python](https://github.com/mailerlite/mailerlite-python) * [MailerLite Ruby](https://github.com/mailerlite/mailerlite-ruby) * [MailerLite Rust](https://github.com/mailerlite/mailerlite-rust) ## Authentication [#authentication] ### API keys [#api-keys] API keys are a quick way to implement machine-to-machine authentication without any direct inputs from a human beyond initial setup. For example, you might want to run a scheduled job to sync your CRM data to your MailerLite account. You can generate an API key by opening [MailerLite](https://dashboard.mailerlite.com/), navigating to [Integrations](https://dashboard.mailerlite.com/integrations) and choosing [MailerLite API](https://dashboard.mailerlite.com/integrations/api). Then click "Generate new token". Give it a name to help you identify where it's used in the future, e.g. "CRM sync job - production". Once the key is generated, please copy and store it immediately. We will not be able to show this API key again in the future, as we don't store API keys in plain text for security reasons. If you lose it, you will have to replace it with a new API key. Once you have your API key, provide it in an `Authorization` header together with your request payload, where XXX is your token: ```http Authorization: Bearer XXX ``` If you fail to provide a valid token, you'll get this response on all requests. ```http Response Code: 401 Unauthorized ``` ```json { "message": "Unauthenticated." } ``` ### API keys lifecycle & user deletion [#api-keys-lifecycle--user-deletion] API keys are permanently bound to the user who created them. If the user is removed from the account or the user account is deleted, the API key will stop working and will no longer authenticate any requests. ## Versioning [#versioning] All requests use the latest version, unless you override the API version. To lock down the API version, provide the current date at the time of implementation through `X-Version` header. ```http X-Version: 2038-01-19 ``` ## Validation errors [#validation-errors] You might encounter validation errors when sending requests to API endpoints. They will come in the following format ```http Response Code: 422 Unprocessable Entity Content-Type: application/json ``` ```json { "message": "The given data was invalid.", "errors": { "email": ["The email must be a valid email address."] } } ``` ## Rate limits [#rate-limits] MailerLite API has a global rate limit of 120 requests per minute. If you exceed that rate limit you will receive a 429 error response with a “Too Many Attempts” message. If you think you will be hitting these limits, please use [batch endpoint](/api/batching) and/or implement backoff strategy that would even out the requests over time. ```http Response Code: 429 Too Many Attempts Content-Type: application/json X-RateLimit-Limit: 120 X-RateLimit-Remaining: 0 Retry-After: 119 ``` ```json { "message": "Too Many Attempts." } ``` ### Import rate limits [#import-rate-limits] Import creation endpoints have a separate rate limit of **5 requests per minute**. This applies to: * `POST /api/subscribers/import` * `POST /api/groups/{group_id}/import-subscribers` * Batch requests where all items are `POST api/subscribers` (subscriber upserts) If you exceed this limit you will receive a `429` response. Use the `Retry-After` header value to know when you can retry. ```http Response Code: 429 Too Many Requests Content-Type: application/json Retry-After: 60 ``` ```json { "message": "You're being rate limited on import creation." } ``` ### HTTP status codes [#http-status-codes] MailerLite returns standard HTTP response codes. | Code | Name | Explanation | | ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | The request was accepted. | | 201 | Created | Resource was created. | | 202 | Accepted | The request was accepted and further actions are taken in the background. | | 204 | No Content | The request was accepted and there is nothing to return. | | 400 | Bad Request | There was an error when processing your request. Please adjust your request based on the endpoint requirements and try again. | | 401 | Unauthorized | The provided API token is invalid. | | 403 | Forbidden | The action is denied for that account or a particular API token. | | 404 | Not Found | The requested resource does not exist on the system. | | 405 | Method Not Allowed | HTTP method is not supported by the requested endpoint. | | 408 | Request Timeout | There is an error on our system. [Please contact support](https://www.mailerlite.com/contact-us) | | 422 | Unprocessable Entity | There was a validation error found when processing the request. Please adjust it based on the endpoint requirements and try again. | | 429 | Too Many Requests | There were too many requests made to the API. | | 500 | Internal Server Error | There was an error on our system. [Please contact support](https://www.mailerlite.com/contact-us) | | 502 | Bad Gateway | There was an error on our system. [Please contact support](https://www.mailerlite.com/contact-us) | | 503 | Service Unavailable | There was an error on our system. [Please contact support](https://www.mailerlite.com/contact-us) | | 504 | Gateway Timeout | There was an error on our system. [Please contact support](https://www.mailerlite.com/contact-us) | More info on HTTP response codes can be found on [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). ## Terms of service [#terms-of-service] Before implementing any integration, please make sure you're familiar with [MailerLite's terms of service](https://www.mailerlite.com/legal/terms-of-service). As stated in the ToC, if you collect subscribers on your own (as opposed to using MailerLite forms), you must accept responsibility for abuse prevention: > \<..>you must ensure that the subscribers are collected in accordance with the industry best practice and requirements set out in these Terms and Anti-Spam Policy. You are responsible for preventing any type of abuse when collecting new subscribers through your own generated API key. ## Branding [#branding] You can use our [brand assets ](https://www.mailerlite.com/brand-assets) within [these guidelines](https://www.mailerlite.com/legal/intellectual-property-guidelines). # Welcome to MailerLite API docs (/) ## Frequently asked questions [#frequently-asked-questions] ### What is the difference between this and Classic API? [#what-is-the-difference-between-this-and-classic-api] This is the latest version of the MailerLite API and it follows [date-based versioning](/getting-started#versioning). We released it on March 22nd, 2022 alongside the new version of MailerLite. API V1 and V2 only work with MailerLite Classic and will eventually be deprecated. ### Which account version do I use? [#which-account-version-do-i-use] Accounts created before March 22nd, 2022 use MailerLite Classic. Accounts created after March 22nd, 2022 use the new MailerLite. ### Which API version should I use? [#which-api-version-should-i-use] MailerLite Classic account users should use API V1 or V2, but [consider eventually migrating to the new MailerLite](https://www.mailerlite.com/help/migration). All new MailerLite accounts should use this latest and improved API. # Automations (/api/automations) You can view your automations and their stats ## List all automations [#list-all-automations] If you want to get all of your automations use this `GET` request ```http request GET https://connect.mailerlite.com/api/automations ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | ---------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | filter\[enabled] | boolean | no | Must be one of the following: `true` (for active) and `false` (for inactive). Defaults to return all automations | | filter\[name] | string | no | Must be a string | | filter\[group] | string | no | Must be a valid group id. Returns all automations that use the group in their trigger configuration | | page | integer | no | Defaults to 1 | | limit | integer | no | Defaults to 10 | ### Response [#response] ``` Response code: 200 OK ``` ```json { "data": [ { "id": "57444257882965766", "name": "Automation 1", "enabled": false, "trigger_data": { "track_ecommerce": false, "repeatable": false, "valid": true, }, "steps": [ { "id": "57444257892403137", "type": "delay", "parent_id": null, "unit": "minutes", "complete": true, "created_at": "2022-06-09 13:58:33", "updated_at": "2022-06-09 13:58:33", "value": "5", "description": "Wait for 5 minutes" }, { "id": "57444261587584962", "type": "email", "parent_id": "57444257892403137", "name": "mail", "subject": "mail {$name}", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "email_id": "57444261557176071", "email": { "id": "57444261557176071", "account_id": "1", "emailable_id": "57444257882965766", "emailable_type": "automations", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "name": "mail", "subject": "mail {$name}", "plain_text": null, "screenshot_url": null, "preview_url": null, "created_at": "2022-06-09 13:58:36", "updated_at": "2022-06-09 13:58:42", "is_designed": true, "language_id": 4, "is_winner": false, "stats": { "sent": 0, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true }, "language_id": 4, "complete": true, "created_at": "2022-06-09 13:58:36", "updated_at": "2022-06-09 13:58:36", "track_opens": true, "google_analytics": null, "tracking_was_disabled": false, "description": "Send \"mail {$name}\" email" } ], "triggers": [ { "id": "80916950725690939", "type": "subscriber_joins_group", "group_ids": [ "80916981736277582" ], "groups": [ { "id": "80916981736277582", "name": "My Group", "url": null } ], "exclude_group_ids": [], "excluded_groups": [], "broken": false } ], "complete": true, "broken": false, "warnings": [], "emails_count": 1, "first_email_screenshot_url": null, "stats": { "completed_subscribers_count": 0, "subscribers_in_queue_count": 0, "bounce_rate": { "float": 0, "string": "0%" }, "click_to_open_rate": { "float": 0, "string": "0%" }, "sent": 0, "opens_count": 0, "unique_opens_count": null, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": null, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" } }, "created_at": "2022-06-09 13:58:33", "has_banned_content": false, "qualified_subscribers_count": 63 } ], "links": { "first": "https://connect.mailerlite.com/api/automations?page=1", "last": "https://connect.mailerlite.com/api/automations?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/automations?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/automations", "per_page": 10, "to": 1, "total": 1 }, "aggregations": { "sum": 24 } } ``` ## Get an automation [#get-an-automation] If you want to fetch a specific automation you can use this `GET` endpoint ```http request GET https://connect.mailerlite.com/api/automations/{automation_id} ``` ### Response [#response-1] ``` Response code: 200 OK ``` ```json { "data": { "id": "57444257882965766", "name": "Automation 1", "enabled": false, "trigger_data": { "track_ecommerce": false, "repeatable": false, "valid": true }, "steps": [ { "id": "57444257892403137", "type": "delay", "parent_id": null, "unit": "minutes", "complete": true, "created_at": "2022-06-09 13:58:33", "updated_at": "2022-06-09 13:58:33", "value": "5", "description": "Wait for 5 minutes" }, { "id": "57444261587584962", "type": "email", "parent_id": "57444257892403137", "name": "mail", "subject": "mail {$name}", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "email_id": "57444261557176071", "email": { "id": "57444261557176071", "account_id": "1", "emailable_id": "57444257882965766", "emailable_type": "automations", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "name": "mail", "subject": "mail {$name}", "plain_text": null, "screenshot_url": null, "preview_url": null, "created_at": "2022-06-09 13:58:36", "updated_at": "2022-06-09 13:58:42", "is_designed": true, "language_id": 4, "is_winner": false, "stats": { "sent": 0, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true }, "language_id": 4, "complete": true, "created_at": "2022-06-09 13:58:36", "updated_at": "2022-06-09 13:58:36", "track_opens": true, "google_analytics": null, "tracking_was_disabled": false, "description": "Send \"mail {$name}\" email" } ], "triggers": [ { "id": "80916950725690939", "type": "subscriber_joins_group", "group_ids": [ "80916981736277582" ], "groups": [ { "id": "80916981736277582", "name": "My Group", "url": null } ], "exclude_group_ids": [], "excluded_groups": [], "broken": false } ], "complete": true, "broken": false, "warnings": [], "emails_count": 1, "first_email_screenshot_url": null, "stats": { "completed_subscribers_count": 0, "subscribers_in_queue_count": 0, "bounce_rate": { "float": 0, "string": "0%" }, "click_to_open_rate": { "float": 0, "string": "0%" }, "sent": 0, "opens_count": 0, "unique_opens_count": null, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": null, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" } }, "created_at": "2022-06-09 13:58:33", "has_banned_content": false, "qualified_subscribers_count": 63 } } ``` ### Error [#error] When providing an invalid automation id ```http Response code: 404 Not Found ``` ## Get the subscriber activity for an automation [#get-the-subscriber-activity-for-an-automation] If you want to fetch the subscriber activity for an automation use this `GET` request ```http request GET https://connect.mailerlite.com/api/automations/{automation_id}/activity ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | ------------------------ | ------- | -------- | --------------------------------------------------------------------------------------- | | filter\[status] | string | yes | Must be one of the following: `completed`, `active`, `canceled`, `failed` | | filter\[date\_from] | date | no | Must be in the format `Y-m-d`. Relevant for statuses: `completed`, `canceled`, `failed` | | filter\[date\_to] | date | no | Must be in the format `Y-m-d`. Relevant for statuses: `completed`, `canceled`, `failed` | | filter\[scheduled\_from] | date | no | Must be in the format `Y-m-d`. Relevant for `active` status | | filter\[scheduled\_to] | date | no | Must be in the format `Y-m-d`. Relevant for `active` status | | filter\[search] | string | no | Must be a subscriber email | | page | integer | no | Defaults to 1 | | limit | integer | no | Defaults to 10 | ### Response [#response-2] ``` Response code: 200 OK ``` ```json { "data": [ { "id": "63060835041281261", "status": "Completed", "date": "2022-08-10 14:13:08", "reason": null, "reason_description": "", "stepRuns": [ { "id": "63060835092661486", "step_id": "63060773780325602", "description": "Wait for 10 minutes", "scheduled_for": "2022-08-10 14:12:11" }, { "id": "63062186887480569", "step_id": "61226379035805534", "description": "Send \"Hello\" email", "scheduled_for": null } ], "nextStep": { "id": "76468141616531049", "type": "condition", "parent_id": "61226379035805534", "complete": true, "broken": false, "yes_step_id": "76468160915572330", "no_step_id": null, "matching_type": "any", "conditions": [ { "type": "custom_fields", "field_id": "5", "action": "contains", "action_value": "unknown", "field": { "id": "5", "name": "City", "type": "text" } } ], "created_at": "2022-07-21 07:54:02", "updated_at": "2022-07-21 07:54:02", "description": "Check some condition" }, "currentStep": { "id": "61226379035805534", "type": "email", "parent_id": "63060773780325602", "name": "gfg", "subject": "gfg", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "email_id": "61226396694873374", "email": { "id": "61226396694873374", "account_id": "1", "emailable_id": "61041127433700472", "emailable_type": "automations", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "name": "Hello", "subject": "Hello", "plain_text": null, "screenshot_url": null, "preview_url": null, "created_at": "2022-07-21 07:54:02", "updated_at": "2022-08-10 14:13:08", "is_designed": true, "language_id": 4, "is_winner": false, "stats": { "sent": 3, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true }, "language_id": 4, "complete": true, "created_at": "2022-07-21 07:53:45", "updated_at": "2022-08-10 13:50:40", "track_opens": true, "google_analytics": null, "tracking_was_disabled": false, "description": "Send \"gfg\" email" } } ], "links": { "first": "https://connect.mailerlite.com/api/automations/{automation_id}/activity?page=1", "last": "https://connect.mailerlite.com/api/automations/{automation_id}/activity?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/automations/{automation_id}/activity?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/automations/{automation_id}/activity", "per_page": 10, "to": 3, "total": 3 } } ``` ### Error [#error-1] When providing an invalid automation id ```http Response code: 404 Not Found ``` ## Create draft automation [#create-draft-automation] If you want to create draft automations use this `POST` request ```http request POST https://connect.mailerlite.com/api/automations ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | ---------------- | | name | string | yes | Must be a string | ### Response [#response-3] ``` Response code: 201 Created ``` ```json { "data": { "id": "100000000000000000", "name": "Created_automation", "enabled": false, "trigger_data": { "track_ecommerce": false }, "warnings": [], "stats": { "completed_subscribers_count": 0, "subscribers_in_queue_count": 0, "bounce_rate": { "float": 0, "string": "0%" }, "click_to_open_rate": { "float": 0, "string": "0%" }, "sent": null, "opens_count": null, "unique_opens_count": null, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": null, "unique_clicks_count": null, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": null, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": null, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": null, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": null, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forward_rate": { "float": 0, "string": "0%" }, "social_interactions_count": null, "social_interaction_rate": { "float": 0, "string": "0%" } }, "created_at": "2024-08-01 00:00:00", "has_banned_content": false, "steps": [] } } ``` ## Delete automation [#delete-automation] If you want to delete automation use this `DELETE` request ```http request DELETE https://connect.mailerlite.com/api/automations/{automation_id} ``` ### Response [#response-4] ``` Response code: 204 No Content ``` # Batching (/api/batching) The batch endpoint can be used to make multiple request to our api in a single call ```http POST /api/batch ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | ------------------ | ------ | -------- | --------------------------------------------------------------------------------- | | requests | array | required | Array of objects containing required method and path properties and optional body | | requests.\*.method | string | required | The method type of the intended request: GET, POST, PUT, DELETE, PATCH | | requests.\*.path | string | required | The relative path of api endpoint. Must start with `api/` | | requests.\*.body | object | optional | Objects containing properties for the body of the request | ### Restrictions [#restrictions] A maximum of 50 requests can be performed in a single batch
The order of response objects is the same as the order in which they were sent
Webhooks are not yet supported in batch requests
### Rate limits [#rate-limits] When a batch request consists entirely of `POST api/subscribers` requests (subscriber upserts), the API automatically processes them as a bulk import internally. This import path is subject to a separate **5 requests per minute** rate limit, in addition to the global API rate limit. When the import rate limit is exceeded, the batch will return a `429` response directly: ``` Response Code: 429 Too Many Requests ``` ```json { "message": "You're being rate limited on import creation." } ``` ### Response [#response] ``` Response Code: 200 OK ``` ```json { "total": 1, "successful": 1, "failed": 0, "responses": [ { "code": 200, "body": { "data": [ { "id": "1", "name": "test field", "key": "test_field", "type": "text" }, { "id": "2", "name": "new field", "key": "new_field", "type": "text" } ] } } ] } ``` ### Error [#error] If invalid data has been passed ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "requests.0.method": ["The requests.1.method field is required."], "requests.0.path": ["The requests.0.path field is required."] } } ``` If one of the batched requests has failed the whole batch will still be processed and the payload for the relevant errored batch will return the error ```json { "total": 1, "successful": 0, "failed": 1, "responses": [ { "code": 422, "body": { "message": "The given data was invalid.", "errors": { "requests.0.method": ["The name field is required."] } } } ] } ``` # Campaign languages (/api/campaign-languages) Use this `GET` request to get a list of all campaign languages available ```http request GET https://connect.mailerlite.com/api/campaigns/languages ``` ### Response [#response] ```http Response code: 200 OK ``` ```json { "data": [ { "id": "4", "shortcode": "en", "iso639": "en-US", "name": "English", "direction": "ltr" } ] } ``` # Campaigns (/api/campaigns) You can create, update or send campaigns ## Campaign list [#campaign-list] If you want to get a list of all of your campaigns based on status or type use this `GET` request ```http request GET https://connect.mailerlite.com/api/campaigns ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------------- | ------- | -------- | ------------------------------------------------------------------------------ | | filter\[status] | string | no | Must be one of the following: sent, draft, ready. Defaults to ready | | filter\[type] | string | no | Must be one of the following: regular, ab, resend, rss. Defaults to return all | | limit | integer | no | Defaults to 25 | | page | integer | no | Defaults to 1 | ### Response [#response] ```http Response Code: 200 OK ``` ```json { "data": [ { "id": "1", "account_id": "1", "name": "dummy campaign", "type": "regular", "status": "sent", "missing_data": [], "settings": { "track_opens": true, "use_google_analytics": false, "ecommerce_tracking": false }, "filter": [ [ { "operator": "in_any", "args": [ "groups", [ "42" ] ] } ] ], "filter_for_humans": [ [ "In any group: dummy group" ] ], "delivery_schedule": "instant", "language_id": "4", "created_at": "2022-07-26 15:07:52", "updated_at": "2022-07-26 15:12:17", "scheduled_for": "2022-07-26 15:11:51", "queued_at": "2022-07-26 15:12:04", "started_at": "2022-07-26 15:12:04", "finished_at": "2022-07-26 15:12:17", "stopped_at": null, "default_email_id": "61706700654118223", "emails": [ { "id": "1", "account_id": "1", "emailable_id": "12", "emailable_type": "campaigns", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "reply_to": "reply-to@mailerlite.io", "name": null, "subject": "hello", "plain_text": "Hello,\n\nYou have received a newsletter from {$account}.\n\nHowever, your email software can't display HTML emails. You can view the newsletter by clicking here: {$url}\nYou're receiving this newsletter because you have shown interest in {$account}.\nNot interested anymore? Click here to unsubscribe:\n{$unsubscribe}", "screenshot_url": null, "preview_url": null, "created_at": "2022-07-26 15:08:15", "updated_at": "2022-07-26 15:15:29", "is_designed": true, "language_id": null, "is_winner": false, "stats": { "sent": 10, "opens_count": 6, "unique_opens_count": 5, "open_rate": { "float": 0.5, "string": "50%" }, "clicks_count": 2, "unique_clicks_count": 2, "click_rate": { "float": 0.2, "string": "20%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true } ], "used_in_automations": false, "type_for_humans": "Regular", "stats": { "sent": 10, "opens_count": 6, "unique_opens_count": 5, "open_rate": { "float": 0.5, "string": "50%" }, "clicks_count": 2, "unique_clicks_count": 2, "click_rate": { "float": 0.2, "string": "20%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0, "click_to_open_rate": { "float": 1, "string": "100%" } }, "is_stopped": false, "has_winner": null, "winner_version_for_human": null, "winner_sending_time_for_humans": null, "winner_selected_manually_at": null, "uses_ecommerce": false, "uses_survey": true, "can_be_scheduled": false, "warnings": [], "initial_created_at": null, "is_currently_sending_out": false } ], "links": { "first": "https://connect.mailerlite.com/api/campaigns?page=1", "last": "https://connect.mailerlite.com/api/campaigns?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/campaigns?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/campaigns", "per_page": 100, "to": 1, "total": 1, "aggregations": { "sum": 2, "draft": 1, "ready": 0, "sent": 1 } } } ``` ## Get a campaign [#get-a-campaign] You can fetch an existing campaign using this `GET` request ```http request GET https://connect.mailerlite.com/api/campaigns/{campaign_id} ``` ### Response [#response-1] ```http Response code: 200 OK ``` ```json { "data": { "id": "1", "account_id": "1", "name": "Dummy campaign", "type": "regular", "status": "draft", "missing_data": [], "settings": { "track_opens": true, "use_google_analytics": false, "ecommerce_tracking": false }, "filter": [ [ { "operator": "in_any", "args": [ "groups", [ "42" ] ] } ] ], "filter_for_humans": [ [ "In any group: dummy group" ] ], "delivery_schedule": "instant", "language_id": "4", "created_at": "2022-07-26 15:07:52", "updated_at": "2022-07-26 15:12:17", "scheduled_for": "2022-07-26 15:11:51", "queued_at": "2022-07-26 15:12:04", "started_at": "2022-07-26 15:12:04", "finished_at": "2022-07-26 15:12:17", "stopped_at": null, "default_email_id": "61706700654118223", "emails": [ { "id": "1", "account_id": "1", "emailable_id": "12", "emailable_type": "campaigns", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "reply_to": "reply-to@mailerlite.io", "name": null, "subject": "hello", "plain_text": "Hello,\n\nYou have received a newsletter from {$account}.\n\nHowever, your email software can't display HTML emails. You can view the newsletter by clicking here: {$url}\nYou're receiving this newsletter because you have shown interest in {$account}.\nNot interested anymore? Click here to unsubscribe:\n{$unsubscribe}", "screenshot_url": null, "preview_url": null, "created_at": "2022-07-26 15:08:15", "updated_at": "2022-07-26 15:15:29", "is_designed": true, "language_id": null, "is_winner": false, "stats": { "sent": 10, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true } ], "used_in_automations": false, "type_for_humans": "Regular", "is_stopped": false, "has_winner": null, "winner_version_for_human": null, "winner_sending_time_for_humans": null, "winner_selected_manually_at": null, "uses_ecommerce": false, "uses_survey": true, "can_be_scheduled": false, "warnings": [], "initial_created_at": null, "is_currently_sending_out": false } } ``` ### Error [#error] When providing an invalid campaign id ```http Response code: 404 Not Found ``` ## Create a campaign [#create-a-campaign] You can create a campaign using this `POST` request ```http request POST https://connect.mailerlite.com/api/campaigns ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | -------------------------------------------------------------- | ------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | yes | Maximum string length of 255 characters | | language\_id | integer | no | Used to define the language in the unsubscribe template. Must be a valid language id. Defaults to english | | type | string | yes | Must be one of the following: `regular`, `ab`, `resend`, `multivariate`. Types `resend` and `multivariate` are only available for accounts on growing or advanced plans | | emails | array | yes | Must contain 1 email object item, unless campaign type is multivariate with content testing. For multivariate content test, it must contain the amount of content test variations | | emails.\*.subject | string | yes, unless multivariate campaign | Maximum string length of 255 characters | | emails.\*.from\_name | string | yes, unless multivariate campaign | Maximum string length of 255 characters | | emails.\*.from | string | yes, unless multivariate campaign | Must be a valid email address that has been already verified on MailerLite | | emails.\*.reply\_to | string | no | Must be a valid `reply_to` email address that has been already verified on MailerLite | | emails.\*.content | string | no | The content must be valid HTML, and the account must be on the Advanced plan. The email body must include an unsubscribe link, account name, address, and country. Otherwise, the default email footer will be added. [Learn more.](https://www.mailerlite.com/help/how-to-use-the-custom-html-editor) | | groups | array | no | Must contain valid group ids belonging to the account | | segments | array | no | Must contain valid segment ids belonging to the account. If both groups and segments are provided, only segments are used | | ab\_settings | object | only if type is `ab` | All items of the array are required | | ab\_settings\[test\_type] | string | only if type is `ab` | Must be one of the following: `subject`, `sender`, `sending_time` | | ab\_settings\[select\_winner\_by] | string | only if type is `ab` and test type is not `sending_time` | Must be one of the following: `o` (for opens), `c` (for clicks) | | ab\_settings\[after\_time\_amount] | integer | only if type is `ab` and test type is not `sending_time` | Defines the amount of wait time for the ab testing | | ab\_settings\[after\_time\_unit] | string | only if type is `ab` and test type is not `sending_time` | Defines the unit of the wait time. Must be one of the following: `h` (for hours) or `d` (for days) | | ab\_settings\[test\_split] | integer | only if type is `ab` | Must be between 5 and 25 for test types `subject` and `sender` and 100 for `sending_time` test type | | ab\_settings\[b\_value] | object | only if type is `ab` and test type is not `sending_time` | Must contain the items for the b version of the campaign | | ab\_settings\[b\_value]\[subject] | string | only if ab test type is `subject` | Maximum string length of 255 characters | | ab\_settings\[b\_value]\[from\_name] | string | only if ab test type is `sender` | Maximum string length of 255 characters | | ab\_settings\[b\_value]\[from] | string | only if ab test type is `sender` | Must be a valid email address that has been already verified on MailerLite | | resend\_settings | object | only if type is `resend` | All items of the array are required | | resend\_settings\[test\_type] | string | only if type is `resend` | Must be one of the following: `subject` | | resend\_settings\[select\_winner\_by] | string | only if type is `resend` | Defines the metric on which the recipients of the second email are selected. Must be one of the following: `o` (did not open the email), `c` (did not click the email) | | resend\_settings\[b\_value] | object | only if type is `resend` | Must contain the items for the auto resend of the campaign | | resend\_setings\[b\_value]\[subject] | string | only if type is `resend` | Maximum string length of 255 characters | | multivariate\_settings | object | only if type is `multivariate` | All items of the array are required | | multivariate\_settings\[test\_variants] | object | only if type is `multivariate` | Must contain all 4 test variant options: subject, sender, content and sending\_time, however the total amount of email combinations must not exceed 8 | | multivariate\_settings\[test\_variants]\[subject] | array | only if type is `multivariate` | Must contain an array of subject variants. Must contain at least 1 | | multivariate\_settings\[test\_variants]\[subject.\*] | string | only if type is `multivariate` | Maximum string length of 255 characters | | multivarite\_settings\[test\_variants]\[sender] | array | only if type is `multivariate` | Must contain an array of sender variants. Must contain at least 1 | | multivariate\_settings\[test\_variants]\[sender.\*] | object | only if type is `multivariate` | Must contain from and from\_name | | multivariate\_settings\[test\_variants]\[sender.\*.from] | string | only if type is `multivariate` | Must be a valid email address that has been already verified on MailerLite | | multivariate\_settings\[test\_variants]\[sender.\*.from\_name] | string | only if type is `multivariate` | Maximum string length of 255 characters | | multivarite\_settings\[test\_variants]\[content] | integer | only if type is `multivariate` | Must be a number between 1 and 8 | | multivarite\_settings\[test\_variants]\[sending\_time] | integer | only if type is `multivariate` | Must be a number between 1 and 8 | | multivarite\_settings\[select\_winner\_by] | string | only if type is `multivariate` and test type is not `sending_time` | Must be one of the following: `o` (for opens), `c` (for clicks) | | multivarite\_settings\[after\_time\_amount] | integer | only if type is `multivariate` and test type is not `sending_time` | Defines the amount of wait time for the ab testing | | multivarite\_settings\[after\_time\_unit] | string | only if type is `multivariate` and test type is not `sending_time` | Defines the unit of the wait time. Must be one of the following: `h` (for hours) or `d` (for days) | | multivarite\_settings\[test\_split] | integer | only if type is `multivariate` | Must be between 10 and 50 when sending time is not tested and 100 when sending time is tested | | settings | object | no | Object containing campaign configuration options such as ecommerce tracking | | settings\[ecommerce\_tracking] | bool | no | If campaign content contains ecommerce shop URLs, ecommerce link tracking will be enabled when set to true | ### Response [#response-2] ```http Response code: 200 OK ``` ```json { "data": { "id": "1", "account_id": "1", "name": "Dummy campaign", "type": "regular", "status": "draft", "missing_data": [], "settings": { "track_opens": true, "use_google_analytics": false, "ecommerce_tracking": false }, "filter": [ [ { "operator": "in_any", "args": [ "groups", [ "42" ] ] } ] ], "filter_for_humans": [ [ "In any group: dummy group" ] ], "delivery_schedule": "instant", "language_id": "4", "created_at": "2022-07-26 15:07:52", "updated_at": "2022-07-26 15:12:17", "scheduled_for": "2022-07-26 15:11:51", "queued_at": "2022-07-26 15:12:04", "started_at": "2022-07-26 15:12:04", "finished_at": "2022-07-26 15:12:17", "stopped_at": null, "default_email_id": "61706700654118223", "emails": [ { "id": "1", "account_id": "1", "emailable_id": "12", "emailable_type": "campaigns", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "reply_to": "reply-to@mailerlite.io", "name": null, "subject": "hello", "plain_text": "Hello,\n\nYou have received a newsletter from {$account}.\n\nHowever, your email software can't display HTML emails. You can view the newsletter by clicking here: {$url}\nYou're receiving this newsletter because you have shown interest in {$account}.\nNot interested anymore? Click here to unsubscribe:\n{$unsubscribe}", "screenshot_url": null, "preview_url": null, "created_at": "2022-07-26 15:08:15", "updated_at": "2022-07-26 15:15:29", "is_designed": true, "language_id": null, "is_winner": false, "stats": { "sent": 10, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true } ], "used_in_automations": false, "type_for_humans": "Regular", "is_stopped": false, "has_winner": null, "winner_version_for_human": null, "winner_sending_time_for_humans": null, "winner_selected_manually_at": null, "uses_ecommerce": false, "uses_survey": true, "can_be_scheduled": false, "warnings": [], "initial_created_at": null, "is_currently_sending_out": false } } ``` ### Error [#error-1] When campaign request has missing parameters ``` Response code: 422 Unprocessable entity ``` ```json { "message": "The given data was invalid.", "errors": { "type": ["The selected type is invalid."] } } ``` ## Update campaign [#update-campaign] If you want to update a campaign that is currently with `draft` status, use this `PUT` request ```http request PUT https://connect.mailerlite.com/api/campaigns/{campaign_id} ``` ### Request body [#request-body-1] | Parameter | Type | Required | Limitations | | ------------------------------------- | ------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | yes | Maximum string length of 255 characters | | language\_id | integer | no | Used to define the language in the unsubscribe template. Must be a valid language id. Defaults to english | | emails | array | yes | Must contain 1 email object item | | emails.\*.subject | string | yes | Maximum string length of 255 characters | | emails.\*.from\_name | string | yes | Maximum string length of 255 characters | | emails.\*. from | string | yes | Must be a valid email address that has been already verified on MailerLite | | emails.\*.content | string | no | The content must be valid HTML, and the account must be on the Advanced plan. The email body must include an unsubscribe link, account name, address, and country. Otherwise, the default email footer will be added. [Learn more.](https://www.mailerlite.com/help/how-to-use-the-custom-html-editor) | | groups | array | no | Must contain valid group ids belonging to the account | | segments | array | no | Must contain valid segment ids belonging to the account. If both groups and segments are provided, only segments are used | | ab\_settings | object | only if type is `ab` | All items of the array are required | | ab\_settings\[test\_type] | string | only if type is `ab` | Must be one of the following: `subject`, `sender`, `sending_time` | | ab\_settings\[select\_winner\_by] | string | only if type is `ab` and test type is not `sending_time` | Must be one of the following: `o` (for opens), `c` (for clicks) | | ab\_settings\[after\_time\_amount] | integer | only if type is `ab` and test type is not `sending_time` | Defines the amount of wait time for the ab testing | | ab\_settings\[after\_time\_unit] | string | only if type is `ab`and test type is not `sending_time` | Defines the unit of the wait time. Must be one of the following: `h` (for hours) or `d` (for days) | | ab\_settings\[test\_split] | integer | only if type is `ab` | Must be between 5 and 25 for test types `subject` and `sender` and 100 for `sending_time` test type | | ab\_settings\[b\_value] | object | only if type is `ab` and test type is not `sending_time` | Must contain the items for the b version of the campaign | | ab\_settings\[b\_value]\[subject] | string | only if ab test type is `subject` | Maximum string length of 255 characters | | ab\_settings\[b\_value]\[from\_name] | string | only if ab test type is `sender` | Maximum string length of 255 characters | | ab\_settings\[b\_value]\[from] | string | only if ab test type is `sender` | Must be a valid email address that has been already verified on MailerLite | | resend\_settings | object | only if type is `resend` | All items of the array are required | | resend\_settings\[test\_type] | string | only if type is `resend` | Must be one of the following: `subject` | | resend\_settings\[select\_winner\_by] | string | only if type is `resend` | Defines the metric on which the recipients of the second email are selected. Must be one of the following: `o` (did not open the email), `c` (did not click the email) | | resend\_settings\[b\_value] | object | only if type is `resend` | Must contain the items for the auto resend of the campaign | | resend\_setings\[b\_value]\[subject] | string | only if type is `resend` | Maximum string length of 255 characters | ### Response [#response-3] ```http Response code: 200 OK ``` ```json { "data": { "id": "1", "account_id": "1", "name": "Dummy campaign", "type": "regular", "status": "draft", "missing_data": [], "settings": { "track_opens": true, "use_google_analytics": false, "ecommerce_tracking": false }, "filter": [ [ { "operator": "in_any", "args": [ "groups", [ "42" ] ] } ] ], "filter_for_humans": [ [ "In any group: dummy group" ] ], "delivery_schedule": "instant", "language_id": "4", "created_at": "2022-07-26 15:07:52", "updated_at": "2022-07-26 15:12:17", "scheduled_for": "2022-07-26 15:11:51", "queued_at": "2022-07-26 15:12:04", "started_at": "2022-07-26 15:12:04", "finished_at": "2022-07-26 15:12:17", "stopped_at": null, "default_email_id": "61706700654118223", "emails": [ { "id": "1", "account_id": "1", "emailable_id": "12", "emailable_type": "campaigns", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "name": null, "reply_to": "reply-to@mailerlite.io", "subject": "hello", "plain_text": "Hello,\n\nYou have received a newsletter from {$account}.\n\nHowever, your email software can't display HTML emails. You can view the newsletter by clicking here: {$url}\nYou're receiving this newsletter because you have shown interest in {$account}.\nNot interested anymore? Click here to unsubscribe:\n{$unsubscribe}", "screenshot_url": null, "preview_url": null, "created_at": "2022-07-26 15:08:15", "updated_at": "2022-07-26 15:15:29", "is_designed": true, "language_id": null, "is_winner": false, "stats": { "sent": 10, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true } ], "used_in_automations": false, "type_for_humans": "Regular", "is_stopped": false, "has_winner": null, "winner_version_for_human": null, "winner_sending_time_for_humans": null, "winner_selected_manually_at": null, "uses_ecommerce": false, "uses_survey": true, "can_be_scheduled": false, "warnings": [], "initial_created_at": null, "is_currently_sending_out": false } } ``` ### Error [#error-2] When trying to update a campaign that is not with status `draft` ```http Response code: 422 Unprocessable entity ``` ```json "Campaign is not with status draft" ``` When campaign request has missing parameters ```http Response code: 422 Unprocessable entity ``` ```json { "message": "The given data was invalid.", "errors": { "name": ["The name may not be greater than 255 characters."] } } ``` When providing an invalid campaign id ```http Response code: 404 Not Found ``` ## Schedule a campaign [#schedule-a-campaign] If you want to schedule or send immediately a campaign, use this `POST` request ```http request POST https://connect.mailerlite.com/api/campaigns/{campaign_id}/schedule ``` ### Request body [#request-body-2] | Parameter | Type | Required | Limitations | | --------------------------------------------- | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | delivery | string | yes unless campaign type is rss | Must be one of the following: instant, scheduled, timezone\_based, smart\_sending | | schedule\[date] | string | only for scheduled and smart\_sending delivery type | Must be a date in the future. Campaign must not be of type AB test with sending time test type | | schedule\[hours] | string | only for scheduled or timezone based delivery types | Must be a valid hour in HH format. Campaign must not be of type AB test with sending time test type | | schedule\[minutes] | string | only for scheduled or timezone based delivery types | Must be a valid minute in ii format. Campaign must not be of type AB test with sending time test type | | schedule\[timezone\_id] | integer | no | Must be a valid timezone id, defaults to the account's timezone id. Campaign must not be of type AB test with sending time test type | | resend\[delivery] | string | only for campaign of type auto resend | Must be Must be one of the following: day, scheduled | | resend\[date] | string | only for campaign of type auto resend | Must be a date in the future | | resend\[hours] | string | only for campaign of type auto resend | Must be a valid hour in HH format | | resend\[minutes] | string | only for campaign of type auto resend | Must be a valid minute in ii format | | resend\[timezone\_id] | integer | no | Must be a valid timezone id, defaults to the account's timezone id | | sending\_time\_test\_schedule | array | yes if campaign is of type AB test with sending time test type | Must constain 2 sending times | | sending\_time\_test\_schedule.\*.date | string | yes if campaign is of type AB test with sending time test type | Must be a date in the future | | sending\_time\_test\_schedule.\*.hours | string | yes if campaign is of type AB test with sending time test type | Must be a valid hour in HH format. | | sending\_time\_test\_schedule.\*.minutes | string | yes if campaign is of type AB test with sending time test type | Must be a valid minute in ii format. | | sending\_time\_test\_schedule.\*.timezone\_id | string | yes if campaign is of type AB test with sending time test type | Must be a valid timezone id, defaults to the account's timezone id. | ### Response [#response-4] ```http Response code: 200 OK ``` ```json { "data": { "id": "1", "account_id": "1", "name": "Dummy campaign", "type": "regular", "status": "sent", "missing_data": [], "settings": { "track_opens": true, "use_google_analytics": false, "ecommerce_tracking": false }, "filter": [ [ { "operator": "in_any", "args": [ "groups", [ "42" ] ] } ] ], "filter_for_humans": [ [ "In any group: dummy group" ] ], "delivery_schedule": "instant", "language_id": "4", "created_at": "2022-07-26 15:07:52", "updated_at": "2022-07-26 15:12:17", "scheduled_for": "2022-07-26 15:11:51", "queued_at": "2022-07-26 15:12:04", "started_at": "2022-07-26 15:12:04", "finished_at": "2022-07-26 15:12:17", "stopped_at": null, "default_email_id": "61706700654118223", "emails": [ { "id": "1", "account_id": "1", "emailable_id": "12", "emailable_type": "campaigns", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "name": null, "reply_to": "reply-to@mailerlite.io", "subject": "hello", "plain_text": "Hello,\n\nYou have received a newsletter from {$account}.\n\nHowever, your email software can't display HTML emails. You can view the newsletter by clicking here: {$url}\nYou're receiving this newsletter because you have shown interest in {$account}.\nNot interested anymore? Click here to unsubscribe:\n{$unsubscribe}", "screenshot_url": null, "preview_url": null, "created_at": "2022-07-26 15:08:15", "updated_at": "2022-07-26 15:15:29", "is_designed": true, "language_id": null, "is_winner": false, "stats": { "sent": 10, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true } ], "used_in_automations": false, "type_for_humans": "Regular", "is_stopped": false, "has_winner": null, "winner_version_for_human": null, "winner_sending_time_for_humans": null, "winner_selected_manually_at": null, "uses_ecommerce": false, "uses_survey": true, "can_be_scheduled": false, "warnings": [], "initial_created_at": null, "is_currently_sending_out": false } } ``` ### Error [#error-3] When campaign settings are not complete ``` Response code: 422 Unprocessable entity ``` ```json "Campaign settings missing" ``` When campaign with given ID has not been found for the account ``` Response code: 404 Not found ``` ## Cancel a ready campaign [#cancel-a-ready-campaign] If you wish to cancel a campaign that is currently in a ready state, use this `POST` request ### Request [#request] ```http request POST https://connect.mailerlite.com/api/campaigns/{campaign_id}/cancel ``` ### Response [#response-5] ``` Response code: 200 OK ``` ```json { "data": { "id": "1", "account_id": "1", "name": "Dummy campaign", "type": "regular", "status": "draft", "missing_data": [], "settings": { "track_opens": true, "use_google_analytics": false, "ecommerce_tracking": false }, "filter": [ [ { "operator": "in_any", "args": [ "groups", [ "42" ] ] } ] ], "filter_for_humans": [ [ "In any group: dummy group" ] ], "delivery_schedule": "instant", "language_id": "4", "created_at": "2022-07-26 15:07:52", "updated_at": "2022-07-26 15:12:17", "scheduled_for": null, "queued_at": null, "started_at": null, "finished_at": null, "stopped_at": null, "default_email_id": "61706700654118223", "emails": [ { "id": "1", "account_id": "1", "emailable_id": "12", "emailable_type": "campaigns", "type": "builder", "from": "dummy@mailerlite.io", "from_name": "Dummy Testerson", "name": null, "reply_to": "reply-to@mailerlite.io", "subject": "hello", "plain_text": "Hello,\n\nYou have received a newsletter from {$account}.\n\nHowever, your email software can't display HTML emails. You can view the newsletter by clicking here: {$url}\nYou're receiving this newsletter because you have shown interest in {$account}.\nNot interested anymore? Click here to unsubscribe:\n{$unsubscribe}", "screenshot_url": null, "preview_url": null, "created_at": "2022-07-26 15:08:15", "updated_at": "2022-07-26 15:15:29", "is_designed": true, "language_id": null, "is_winner": false, "stats": { "sent": 10, "opens_count": 0, "unique_opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "unique_clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribes_count": 0, "unsubscribe_rate": { "float": 0, "string": "0%" }, "spam_count": 0, "spam_rate": { "float": 0, "string": "0%" }, "hard_bounces_count": 0, "hard_bounce_rate": { "float": 0, "string": "0%" }, "soft_bounces_count": 0, "soft_bounce_rate": { "float": 0, "string": "0%" }, "forwards_count": 0 }, "send_after": null, "track_opens": true } ], "used_in_automations": false, "type_for_humans": "Regular", "is_stopped": false, "has_winner": null, "winner_version_for_human": null, "winner_sending_time_for_humans": null, "winner_selected_manually_at": null, "uses_ecommerce": false, "uses_survey": true, "can_be_scheduled": false, "warnings": [], "initial_created_at": null, "is_currently_sending_out": false } } ``` ### Error [#error-4] When trying to cancel a campaign sending that is not in a ready state ``` Response code: 400 Bad request ``` When campaign with given ID has not been found for the account ``` Response code: 404 Not found ``` ## Delete a campaign [#delete-a-campaign] If you want to delete a campaign, use this `DELETE` request ```http request DELETE https://connect.mailerlite.com/api/campaigns/{campaign_id} ``` ### Response [#response-6] ```http Response Code: 204 No Content ``` ### Error [#error-5] ```http Response code: 404 Not found ``` ## Get subscribers' activity of a sent campaign [#get-subscribers-activity-of-a-sent-campaign] If you want to get the subscribers' activity of a campaign with status `sent` use this `GET` request ```http request GET https://connect.mailerlite.com/api/campaigns/{campaign_id}/reports/subscriber-activity ``` ### Request body [#request-body-3] | Parameter | Type | Required | Limitations | | --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | filter\[type] | string | no | Must be one of following: `opened`, `unopened`, `clicked`, `unsubscribed`, `forwarded`, `hardbounced`, `softbounced`, `junk`. Defaults to returning all recipients | | filter\[search] | string | no | Must be a subscriber email | | limit | integer | no | Must be one of the following: `10, 25, 50, 100`. Defaults to 50 | | sort | string | no | Must be one of the following: `id`, `updated_at`, `clicks_count`, `opens_count`. Defaults to `id` | | page | integer | no | Defaults to 1 | | include | string | no | Additional resources to include in the response. Currently `subscriber` and `subscriber.groups` are supported. | ### Response [#response-7] ``` Response code: 200 OK ``` ```json { "data": [ { "id":"66201001018787256", "opens_count":1, "clicks_count":0, "subscriber": { "id":"56152210168350162", "email":"dummy@mailerlite.com", "status":"active", "source":"import", "sent":13, "opens_count":1, "clicks_count":0, "open_rate":7.69, "click_rate":0, "ip_address":null, "subscribed_at":"2022-05-26 07:42:00", "unsubscribed_at":null, "created_at":"2022-05-26 07:42:00", "updated_at":"2022-09-14 05:44:16", "fields": { "name":null, "last_name":null, "company":null, "country":null, "city":null, "phone":null, "state":null, "zip":null }, "opted_in_at":null, "optin_ip":null } } ], "links": { "first":"https://connect.mailerlite.com/api/campaigns/66200823885989563/reports/subscriber-activity?page=1", "last":"https://connect.mailerlite.com/api/campaigns/66200823885989563/reports/subscriber-activity?page=1", "prev":null, "next":null }, "meta": { "current_page":1, "from":1, "last_page":1, "links": [ { "url":null, "label":"« Previous", "active":false }, { "url":"https://connect.mailerlite.com/api/campaigns/66200823885989563/reports/subscriber-activity?page=1", "label":"1", "active":true }, { "url":null, "label":"Next »", "active":false } ], "path":"https://connect.mailerlite.com/api/campaigns/66200823885989563/reports/subscriber-activity", "per_page":50, "to":1, "total":1, "aggregations": { "sum":11, "opened":1, "unopened":10, "clicked":0, "unsubscribed":0, "forwarded":0, "hardbounced":0, "softbounced":0, "junk":0 } } } ``` ### Error [#error-6] When providing an invalid campaign id ```http Response code: 404 Not Found ``` ```json { "message": "The given data was invalid.", "errors": { "limit": ["The limit must be one of following: 10, 25, 50, 100"] } } ``` # Fields (/api/fields) Fields can be assigned to subscribers ## List all fields [#list-all-fields] If you want to list all of your fields, use this `GET` endpoint ``` GET https://connect.mailerlite.com/api/fields ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------- | | limit | integer | no | An account can have at most a 100 groups | | page | integer | no | Count starts from 1 | | filter\[keyword] | string | no | Returns partial matches | | filter\[type] | string | no | Can be one of the following: text, number or date | | sort | string | no | Can be one of: `name`, `type`, Defaults to ascending order; prepend `-`, e.g. `-name` for descending order. | ### Response [#response] ```http Response Code: 200 OK ``` ```json { "data": [ { "id": "1", "name": "new field", "key": "new_field", "type": "text" } ], "links": { "first": "https://connect.mailerlite.com/api/fields?page=1", "last": "https://connect.mailerlite.com/api/fields?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/fields?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/fields", "per_page": 100, "to": 1, "total": 1 } } ``` ## Create a field [#create-a-field] If you want to create a field that can be assigned to subscribers, use this `POST` request ```http POST https://connect.mailerlite.com/api/fields ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | -------------------------------- | | name | string | yes | Maximum length of 255 characters | | type | string | yes | Can be text, number or date | ### Response [#response-1] ``` Response Code: 200 OK ``` ```json { "data": { "id": "1", "name": "new field", "key": "new_field", "type": "text" } } ``` ### Error [#error] If invalid data has been passed ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "type": ["The selected type is invalid."] } } ``` ## Update a field [#update-a-field] If you want to update a field, use this `PUT` request ```http PUT https://connect.mailerlite.com/api/fields/{field_id} ``` ### Request body [#request-body-1] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | -------------------------------- | | name | string | yes | Maximum length of 255 characters | ### Response [#response-2] ``` Response Code: 200 OK ``` ```json { "data": { "id": "1", "name": "new field", "key": "new_field", "type": "text" } } ``` ### Error [#error-1] If invalid data has been passed ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "type": ["The name may not be greater than 255 characters."] } } ``` ## Delete a field [#delete-a-field] If you want to delete a field, use this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/fields/{field_id} ``` ### Response [#response-3] ``` Response code: 204 No Content ``` ### Error [#error-2] ``` Response Code: 404 Not found ``` # Forms (/api/forms) You can see your existing forms and their basic stats. ## List all forms [#list-all-forms] If you want to list all forms in your account, send this `GET` request ```http GET https://connect.mailerlite.com/api/forms/{type} ``` Type value is required and can be `popup`, `embedded`, or `promotion`. ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | limit | integer | no | | | page | integer | no | Count starts from 1 | | filter\[name] | string | no | Returns partial matches | | sort | string | no | Can be one of: `created_at`, `name`, `conversions_count`, `opens_count`, `visitors`, `conversion_rate`, `last_registration_at`. Defaults to ascending order; prepend `-`, e.g. `-created_at` for descending order. | ### Response [#response] ```http Response Code: 200 OK ``` ```json { "data": [ { "id": "38965245585131492", "type": "embedded", "slug": "Ec7t3n", "name": "inventore provident ut", "created_at": "2021-11-17 14:42:33", "conversions_count": 0, "opens_count": 0, "conversion_rate": { "float": 0, "string": "0%" }, "settings": [], "last_registration_at": null, "active": false, "is_broken": false, "has_content": false, "can": { "update": true }, "used_in_automations": false, "warnings": [], "double_optin": null, "screenshot_url": null } ], "links": { "first": "https://connect.mailerlite.com/api/forms/embedded?page=1", "last": "https://connect.mailerlite.com/api/forms/embedded?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/forms/embedded?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/forms/embedded", "per_page": 25, "to": 1, "total": 1, "aggregations": { "popup": 3, "embedded": 1, "promotion": 1 } } } ``` ## Get a form [#get-a-form] If you want to fetch a specific form you can use this `GET` request ```http request GET https://connect.mailerlite.com/api/forms/{form_id} ``` ### Response [#response-1] ``` Response code: 200 OK ``` ```json { "data": { "id": "38965245585131492", "type": "embedded", "slug": "Ec7t3n", "name": "inventore provident ut", "created_at": "2021-11-17 14:42:33", "conversions_count": 0, "opens_count": 0, "conversion_rate": { "float": 0, "string": "0%" }, "settings": [], "last_registration_at": null, "active": false, "is_broken": false, "has_content": false, "can": { "update": true }, "used_in_automations": false, "warnings": [], "double_optin": null, "screenshot_url": null } } ``` ### Error [#error] When the form id is invalid ``` Response code: 404 Not Found ``` ## Update a form [#update-a-form] If you want to update a form use this `PUT` request ```http PUT https://connect.mailerlite.com/api/forms/{form_id} ``` The id must a valid form id that belongs to the account ### Request body [#request-body] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | -------------------------------- | | name | string | yes | Maximum length of 255 characters | ### Response [#response-2] ``` Response code: 200 OK ``` ```json { "data": { "id": "38965245585131492", "type": "embedded", "slug": "Ec7t3n", "name": "inventore provident ut", "created_at": "2021-11-17 14:42:33", "conversions_count": 0, "opens_count": 0, "conversion_rate": { "float": 0, "string": "0%" }, "settings": [], "last_registration_at": null, "active": false, "is_broken": false, "has_content": false, "can": { "update": true }, "used_in_automations": false, "warnings": [], "double_optin": null, "screenshot_url": null } } ``` ### Error [#error-1] When the form id is invalid ``` Response code: 404 Not Found ``` If invalid data has been passed ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "name": ["The name may not be greater than 255 characters."] } } ``` ## Delete a form [#delete-a-form] Use this `DELETE` request to delete a form ```http DELETE https://connect.mailerlite.com/api/forms/{form_id} ``` The id must a valid form id that belongs to the account. ### Response [#response-3] ``` Response code: 204 No Content ``` ### Error [#error-2] When the form id is invalid ``` Response code: 404 Not Found ``` ## Get subscribers who signed up to a specific form [#get-subscribers-who-signed-up-to-a-specific-form] If you want to fetch all the subscribers who signed up to a specific form use this `GET` request ```http request GET https://connect.mailerlite.com/api/forms/{form_id}/subscribers ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- | | filter\[status] | string | no | Must be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk. Defaults to active. | | limit | integer | no | Defaults to 25 | | cursor | string | no | Defaults to first page. Cursor value available in response body | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "data": [ { "id": "31986843064993537", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } ], "links": { "first": null, "last": null, "prev": "https://connect.mailerlite.com/api/forms/1234567890/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9", "next": "https://connect.mailerlite.com/api/forms/1234567890/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "meta": { "path": "https://connect.mailerlite.com/api/forms/1234567890/subscribers", "per_page": 25, "next_cursor": "eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "prev_cursor": "eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9" } } ``` ### Error [#error-3] When the form id is invalid ``` Response code: 404 Not Found ``` # Groups (/api/groups) You can see your existing groups or get the list of subscribers belonging to a given group ## List all groups [#list-all-groups] If you want to list all of your groups, you can send this `GET` request ```http GET https://connect.mailerlite.com/api/groups ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | limit | integer | no | An account can have at most a 1000 groups | | page | integer | no | Count starts from 1 | | filter\[name] | string | no | Returns partial matches | | sort | string | no | Can be one of: `name`, `total`, `open_rate`, `click_rate`, `created_at`. Defaults to ascending order; prepend `-`, e.g. `-total` for descending order. | ### Response [#response] ```http Response Code: 200 OK ``` ```json { "data": [ { "id": "1", "name": "dummy group", "active_count": 0, "sent_count": 0, "opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribed_count": 0, "unconfirmed_count": 0, "bounced_count": 0, "junk_count": 0, "created_at": "2022-05-24 11:52:55" } ], "links": { "first": "https://connect.mailerlite.com/api/groups?page=1", "last": "https://connect.mailerlite.com/api/groups?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/groups?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/groups", "per_page": 100, "to": 1, "total": 1 } } ``` ## Create a group [#create-a-group] If you want to create a group, you can send this `POST` request ```http POST https://connect.mailerlite.com/api/groups ``` ### Request [#request] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | -------------------------------- | | name | string | yes | Maximum length of 255 characters | ### Response [#response-1] ```http Response Code: 201 Created ``` ```json { "data": { "id": "1", "name": "dummy group", "active_count": 0, "sent_count": 0, "opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribed_count": 0, "unconfirmed_count": 0, "bounced_count": 0, "junk_count": 0, "created_at": "2022-05-25 14:22:44" } } ``` ### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "name": ["The name may not be greater than 255 characters."] } } ``` ## Update a group [#update-a-group] If you want to update a group you can send this `PUT` request ```http PUT https://connect.mailerlite.com/api/groups/{group_id} ``` ### Request [#request-1] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | -------------------------------- | | name | string | yes | Maximum length of 255 characters | ### Response [#response-2] ```http Response Code: 200 OK ``` ```json { "data": { "id": "1", "name": "dummy group", "active_count": 0, "sent_count": 0, "opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribed_count": 0, "unconfirmed_count": 0, "bounced_count": 0, "junk_count": 0, "created_at": "2022-05-25 14:22:44" } } ``` ### Error [#error-1] ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "name": ["The name may not be greater than 255 characters."] } } ``` ## Delete group [#delete-group] If you want to delete a group, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/groups/{group_id} ``` ### Response [#response-3] ``` Response code: 204 No Content ``` ### Error [#error-2] ``` Response Code: 404 Not found ``` ## Get subscribers belonging to a group [#get-subscribers-belonging-to-a-group] If you want to get all subscribers belonging to a group, send this `GET` request ```http GET https://connect.mailerlite.com/api/groups/{group_id}/subscribers ``` ### Request [#request-2] | Parameter | Type | Required | Limitations | | --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- | | filter\[status] | string | no | Must be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk. Defaults to active. | | limit | integer | no | Number of subscribers to return per page. Defaults to 50. Maximum is 1000. | | cursor | string | no | Defaults to first page. Use `meta.next_cursor` or `meta.prev_cursor` from response to navigate. | | include | string | no | Additional resources to include in the response. Currently, only `groups` is supported. | ### Response [#response-4] ```json { "data": [ { "id": "31986843064993537", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "opted_in_at": null, "optin_ip": null } ], "links": { "first": null, "last": null, "prev": "https://connect.mailerlite.com/api/groups/1234567890/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9", "next": "https://connect.mailerlite.com/api/groups/1234567890/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "meta": { "path": "https://connect.mailerlite.com/api/groups/1234567890/subscribers", "per_page": 25, "next_cursor": "eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "prev_cursor": "eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9" } } ``` ### Error [#error-3] ``` Response Code: 404 Not found ``` ## Assign subscriber to a group [#assign-subscriber-to-a-group] If you want to assign an existing subscriber to a group, send this `POST` request ```http POST https://connect.mailerlite.com/api/subscribers/{subscriber_id}/groups/{group_id} ``` ### Request [#request-3] | Parameter | Type | Required | Limitations | | -------------- | ------- | -------- | --------------------------------- | | subscriber\_id | integer | yes | Must be an existing subscriber id | | group\_id | integer | yes | Must be an existing group id | ### Response [#response-5] ``` Response Code: 200 OK / 201 Created ``` ```json { "data": { "id": "1", "name": "dummy group", "active_count": 0, "sent_count": 0, "opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribed_count": 0, "unconfirmed_count": 0, "bounced_count": 0, "junk_count": 0, "created_at": "2022-05-25 14:22:44" } } ``` ### Error [#error-4] ``` Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "id": ["The selected id is invalid."] } } ``` ## Unassign subscriber from a group [#unassign-subscriber-from-a-group] If you want to unassign an existing subscriber from a group, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/subscribers/{subscriber_id}/groups/{group_id} ``` ### Request [#request-4] | Parameter | Type | Required | Limitations | | -------------- | ------- | -------- | ------------------------------------------- | | subscriber\_id | integer | yes | Must be an existing subscriber id | | group\_id | integer | yes | Must be an existing group id on the account | ### Response [#response-6] ``` Response Code: 204 No Content ``` ### Error [#error-5] ``` Response Code: 404 Not Found ``` ```json { "message": "" } ``` ## Import bulk subscribers to group [#import-bulk-subscribers-to-group] Use this request to bulk import subscribers to a group. The response is a URL to check the import's progress. This endpoint is limited to **5 requests per minute** per API token. ```http POST https://connect.mailerlite.com/api/groups/{group_id}/import-subscribers ``` ### Request [#request-5] | Parameter | Type | Required | Limitations | | --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | subscribers | array | yes | Must be an array of subscribers objects. | | subscribers.\*.email | string | yes | Valid email address as per RFC 2821 | | subscribers.\*.fields | object | no | Object keys must correspond to default or custom field name. Values can only be added this way and will not be removed by omission. | ### Response [#response-7] ``` Response Code: 200 OK ``` ```json { "import_progress_url": "https://connect.mailerlite.com/api/subscribers/import/100000000000000000" } ``` ### Response import progress [#response-import-progress] The response shows a maximum of 5 sample subscribers in arrays. ``` Response Code: 200 OK ``` ```json { "data": { "id": "100000000000000000", "account_id": "1", "total": 100, "processed": 100, "imported": 100, "updated": 0, "errored": 0, "percent": 100, "done": true, "invalid": [], "invalid_count": 0, "mistyped": [], "mistyped_count": 0, "changed": [], "changed_count": 0, "unchanged": [], "unchanged_count": 0, "unsubscribed": [], "unsubscribed_count": 0, "role_based": [], "role_based_count": 0, "suspicious_format": [], "suspicious_format_count": 0, "duplicate": [], "duplicate_count": 0, "banned_import_emails_count": 0, "updated_at": "2024-07-01T01:01:01.000000Z", "undone_at": null, "stopped_at": null, "undo_started_at": null, "finished_at": "2024-07-01T01:30:01.000000Z" } } ``` ### Rate limit error [#rate-limit-error] ``` Response Code: 429 Too Many Requests ``` ```json { "message": "You're being rate limited on import creation." } ``` # Segments (/api/segments) ## List all segments [#list-all-segments] If you want to list all segments in your account, send this `GET` request ```http GET https://connect.mailerlite.com/api/segments ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | ------------------------------------------ | | limit | integer | no | An account can have at most a 250 segments | | page | integer | no | Count starts from 1 | ### Response [#response] ```http Response Code: 200 OK ``` ```json { "data": [ { "id": "1", "name": "Dummy segment", "total": 21, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" } ], "links": { "first": "https://connect.mailerlite.com/api/segments?page=1", "last": "https://connect.mailerlite.com/api/segments?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/segments?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/segments", "per_page": 25, "to": 1, "total": 1 } } ``` ## Get subscribers belonging to a segment [#get-subscribers-belonging-to-a-segment] If you want to get all subscribers belonging to a segment, send this `GET` request ```http GET https://connect.mailerlite.com/api/segments/{segment_id}/subscribers ``` ### Request [#request] | Parameter | Type | Required | Limitations | | --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- | | filter\[status] | string | no | Must be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk. Defaults to active. | | limit | integer | no | | | after | integer | no | The last subscriber id, available in meta.last | | cursor | string | no | Defaults to first page. Cursor value available in response body | ```json { "data": [ { "id": "1", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } ], "links": { "first": null, "last": null, "prev": "https://connect.mailerlite.com/api/segments/1234567890/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9", "next": "https://connect.mailerlite.com/api/segments/1234567890/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "meta": { "path": "https://connect.mailerlite.com/api/segments/1234567890/subscribers", "per_page": 25, "next_cursor": "eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "prev_cursor": "eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9" } } ``` ### Error [#error] ``` Response code: 404 Not Found ``` ## Update segment [#update-segment] If you want to update a segment use this `PUT` endpoint ```http request PUT https://connect.mailerlite.com/api/segments/{segment_id} ``` The id must a valid segment id that belongs to the account ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | -------------------------------- | | name | string | yes | Maximum length of 255 characters | ### Response [#response-1] ``` Response code: 200 OK ``` ```json { "data": { "id": "1", "name": "Dummy segment", "total": 21, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" } } ``` ### Error [#error-1] When the segment id is invalid ``` Response code: 404 Not Found ``` If invalid data has been passed ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "type": ["The name may not be greater than 255 characters."] } } ``` ## Delete segment [#delete-segment] If you wish to delete a segment, use this `DELETE` endpoint ```http request DELETE https://connect.mailerlite.com/api/segments/{segment_id} ``` The id must a valid segment id that belongs to the account ### Response [#response-2] ``` Response code: 204 No Content ``` ### Error [#error-2] When the segment id is invalid ``` Response code: 404 Not Found ``` # Subscribers (/api/subscribers) You can add or update subscribers in your mailing list. ## List all subscribers [#list-all-subscribers] If you want to list all of your subscribers, send this `GET` request ```http GET https://connect.mailerlite.com/api/subscribers ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------- | | filter\[status] | string | no | Must be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk. | | limit | integer | no | Defaults to 25 | | cursor | string | no | Defaults to first page. Cursor value available in response body | | include | string | no | Additional resources to include in the response. Currently, only `groups` is supported. | ### Response [#response] ```json { "data": [ { "id": "31986843064993537", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "opted_in_at": null, "optin_ip": null } ], "links": { "first": null, "last": null, "prev": "https://connect.mailerlite.com/api/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9", "next": "https://connect.mailerlite.com/api/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "meta": { "path": "https://connect.mailerlite.com/api/subscribers", "per_page": 25, "next_cursor": "eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "prev_cursor": "eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9" } } ``` ## Create/upsert subscriber [#createupsert-subscriber] If you want to create or update a subscriber, send this `POST` request ```http POST https://connect.mailerlite.com/api/subscribers ``` If a subscriber already exists, it will be updated with new values. This is non-destructive operation, so omitting fields or groups will not remove them from subscriber. ### Request [#request] | Parameter | Type | Required | Limitations | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | email | string | yes | Valid email address as per RFC 2821 | | fields | object | no | Object keys must correspond to default or custom field name. Values can only be added this way and will not be removed by omission. | | groups | array | no | array must contain existing group ids. Subscriber can only be added to groups this way and will not be removed by omission | | status | string | no | Can be one of the following: active, unsubscribed, unconfirmed, bounced, junk | | subscribed\_at | string | no | Must be a valid date in the format `yyyy-MM-dd HH:mm:ss` | | ip\_address | string | no | Must be a valid ip address | | opted\_in\_at | string | no | Must be a valid date in the format `yyyy-MM-dd HH:mm:ss` | | optin\_ip | string | no | Must be a valid ip address | | unsubscribed\_at | string | no | Must be a valid date in the format `yyyy-MM-dd HH:mm:ss` | | resubscribe | bool | no | Set to true to resubscribe previously unsubscribed subscribers | ``` { "email": "dummy@example.com", "fields": { "name": "Dummy", "last_name": "Testerson" }, "groups": [ "4243829086487936", "14133878422767533", "31985378335392975" ] } ``` ### Response [#response-1] If the subscriber was created: ```http Response Code: 201 Created ``` If the subscriber with specified email was already in the mailing list: ```http Response Code: 200 OK ``` ```json { "data": { "id": "31897397363737859", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-08-31 14:22:08", "unsubscribed_at": null, "created_at": "2021-08-31 14:22:08", "updated_at": "2021-08-31 14:22:08", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "email": ["The email must be a valid email address."] } } ``` ## Update a subscriber [#update-a-subscriber] If you want to update a single subscriber, send this `PUT` request: ```http PUT https://connect.mailerlite.com/api/subscribers/(:id) ``` If a subscriber already exists, their information will be updated. However, please note that if the subscriber’s status is unsubscribed, bounced, or marked as junk, you will not be able to reactivate them due to abuse prevention measures. In such cases, the subscriber can only be reactivated through the app, a form, or a landing page. ### Request [#request-1] | Parameter | Type | Required | Limitations | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | fields | object | no | Object keys must correspond to default or custom field name. Values can only be added this way and will not be removed by omission. | | groups | array | no | array containing existing group ids. Subscriber will be removed from unlisted groups | | status | string | no | Can be one of the following: active, unsubscribed, unconfirmed, bounced, junk | | subscribed\_at | string | no | Must be a valid date in the format `yyyy-MM-dd HH:mm:ss` | | ip\_address | string | no | Must be a valid ip address | | opted\_in\_at | string | no | Must be a valid date in the format `yyyy-MM-dd HH:mm:ss` | | optin\_ip | string | no | Must be a valid ip address | | unsubscribed\_at | string | no | Must be a valid date in the format `yyyy-MM-dd HH:mm:ss` | ``` { "fields": { "name": "Dummy", "last_name": null }, "groups": [ "4243829086487936", "14133878422767533", "31985378335392975" ] } ``` ### Response [#response-2] ```http Response Code: 200 OK ``` ```json { "data": { "id": "31897397363737859", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-08-31 14:22:08", "unsubscribed_at": null, "created_at": "2021-08-31 14:22:08", "updated_at": "2021-08-31 14:22:08", "fields": { "city": null, "company": null, "country": null, "last_name": null, "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } } ``` #### Error [#error-1] ```http Response Code: 422 Unprocessable Entity ``` ```json { "message": "The given data was invalid.", "errors": { "email": ["The email must be a valid email address."] } } ``` ## Fetch a subscriber [#fetch-a-subscriber] If you want to fetch a subscriber, send this `GET` request ```http GET https://connect.mailerlite.com/api/subscribers/(:id or :email) ``` ### Request [#request-2] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | ------------------------------------------------ | | email | string | no | Must provide either valid subscriber id or email | | id | string | no | Must provide either valid subscriber id or email | ``` GET https://connect.mailerlite.com/api/subscribers/31986843064993537 GET https://connect.mailerlite.com/api/subscribers/dummy@example.com ``` ### Response [#response-3] If subscriber exists: ```http Response Code: 200 OK ``` ```json { "data": { "id": "31986843064993537", "email": "dummy@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } } ``` #### Error [#error-2] If the subscriber cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total subscribers count [#fetch-total-subscribers-count] ```http GET https://connect.mailerlite.com/api/subscribers?limit=0 ``` ### Request [#request-3] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | --------------- | | limit | integer | yes | Value must be 0 | ### Response [#response-4] ``` Response Code: 200 OK ``` ```json { "total": 100 } ``` ## Fetch subscriber activity [#fetch-subscriber-activity] ```http GET https://connect.mailerlite.com/api/subscribers/:id/activity-log ``` ### Request [#request-4] | Parameter | Type | Required | Limitations | | ------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | yes | Must provide either valid subscriber id | | filter\[log\_name] | string | no | Must be one of the possible log\_name: campaign\_send, automation\_email\_sent, email\_open, link\_click, email\_bounce, spam\_complaint, unsubscribed, email\_forward, marketing\_preferences\_change or preference\_center. | | limit | integer | no | Defaults to 100 | | page | integer | no | Count starts from 1 | ### Response [#response-5] ``` Response Code: 200 OK ``` ```json { "data": [ { "id": "1235", "log_name": "added_to_group", "subject_id": "1000000000000000", "subject_type": "subscribers", "properties": { "group_name": "test group", "group_id": "1" }, "created_at": "2024-05-01 12:43:29", "updated_at": "2024-05-01 12:43:29" }, { "id": "1234", "log_name": "activated", "subject_id": "1000000000000000", "subject_type": "subscribers", "properties": [], "created_at": "2024-05-01 12:43:29", "updated_at": "2024-05-01 12:43:29" }, { "id": "123456", "log_name": "email_open", "subject_id": "123456", "subject_type": "opens", "properties": { "type": "campaigns", "campaign_id": "123456", "campaign_name": "Example name", "preview_url": "https://example_preview.url" }, "created_at": "2024-09-01 00:00:00", "updated_at": "2024-09-01 00:00:00" } ] } ``` ## Delete a subscriber [#delete-a-subscriber] It will removes the subscriber from your account, but all their information is still kept in case they re-subscribe to your list. If you want to delete a subscriber, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/subscribers/:id ``` ### Request [#request-5] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | ----------------------------------- | | id | string | yes | Valid subscriber id for the account | ### Response [#response-6] ``` Response Code: 204 No Content ``` ### Error [#error-3] ``` Response Code: 404 Not Found ``` ## Forget a subscriber [#forget-a-subscriber] It will removes the subscriber from your account and all information will be completely deleted in 30 days. This feature is GDPR compliant.If you want to forget a subscriber, send this `POST` request ```http POST https://connect.mailerlite.com/api/subscribers/:id/forget ``` ### Request [#request-6] | Parameter | Type | Required | Limitations | | --------- | ------ | -------- | ----------------------------------- | | id | string | yes | Valid subscriber id for the account | ### Response [#response-7] ``` Response Code: 200 OK ``` ```json { "message": "Subscriber data will be completely deleted and forgotten within 30 days.", "data": { "id": "85348545455981948", "email": "bashirian.wilhelmine@yahoo.com", "status": "active", "source": "subscribe app", "sent": 89, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": "140.229.243.225", "subscribed_at": "2023-04-13 14:05:15", "unsubscribed_at": null, "created_at": "2023-04-13 14:05:15", "updated_at": "2023-04-19 05:40:50", "deleted_at": "2023-04-19 05:40:50", "forget_at": "2023-05-19 05:40:50", "fields": { "name": "Carmella", "last_name": "Hegmann", "company": "DuBuque Inc", "country": "Puerto Rico", "city": "Moshemouth", "phone": "1-628-782-7066", "state": null, "zip": null }, "groups": [ { "id": "85348546500363273", "name": "sint incidunt", "active_count": 20, "sent_count": 1284, "opens_count": 0, "open_rate": { "float": 0, "string": "0%" }, "clicks_count": 0, "click_rate": { "float": 0, "string": "0%" }, "unsubscribed_count": 0, "unconfirmed_count": 0, "bounced_count": 0, "junk_count": 0, "created_at": "2023-04-13 14:05:16", "processing": true, "used_in_forms": false, "used_in_sites": false } ], "location": { "id": "1", "title": "New York City", "country_name": "United States of America", "continent_name": "North America", "state_name": "New York", "time_zone": "America/New_York" }, "opted_in_at": null, "optin_ip": null, "email_changed_at": null } } ``` ### Error [#error-4] ``` Response code: 404 Not Found ``` ## Get single import [#get-single-import] If you want to get a single import report, send this `GET` request ```http GET https://connect.mailerlite.com/api/subscribers/import/{import_id} ``` ### Response [#response-8] ``` Response Code: 200 OK ``` ```json { "data": { "id": "47366063630845932", "total": 3, "processed": 3, "imported": 0, "updated": 0, "errored": 3, "percent": 100, "done": true, "file_path": "", "invalid": [], "invalid_count": 0, "mistyped": [], "mistyped_count": 0, "changed": [], "changed_count": 0, "unchanged": [ { "id": "47366064023013357", "email": "dummy_one@import.com" }, { "id": "47366064023013358", "email": "dummy_two+two@import.com" }, { "id": "47366064023013359", "email": "dummy_three@new.com" } ], "unchanged_count": 3, "unsubscribed": [], "unsubscribed_count": 0, "role_based": [], "role_based_count": 0, "banned_import_emails_count": 0, "match_route": "", "source_label": "", "updated_at": "2022-02-18T08:09:58.000000Z", "undone_at": null, "stopped_at": null, "undo_started_at": null, "finished_at": "2022-02-18T08:09:58.000000Z" } } ``` # Timezones (/api/timezones) Use this `GET` request to get all available timezones ```http request GET https://connect.mailerlite.com/api/timezones ``` ### Response [#response] ```http Response code: 200 OK ``` ```json { "data": [ { "id": "370", "name": "Europe/Vilnius", "name_for_humans": "Europe/Vilnius (+03:00)", "offset_name": "+03:00", "offset": 180 } ] } ``` # Webhooks (/api/webhooks) Webhooks allow you to subscribe to real-time notifications about various events that occur in MailerLite. For example, when a new subscriber is added to your account, HTTP POST callback is sent to your provided URL with a payload containing the new subscriber. It allows you to get the most recent updates without constantly polling the API. You can see your existing webhooks, create new, update and delete them. ## Available events [#available-events] | Event | Description | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | subscriber.created | Fires when a new subscriber is added to an account. | | subscriber.updated | Fires when any of the subscriber's custom fields are updated or when they confirm their subscription. | | subscriber.unsubscribed | Fires when a subscriber becomes unsubscribed. | | subscriber.added\_to\_group | Fires when a subscriber is added to a group. | | subscriber.removed\_from\_group | Fires when a subscriber is removed from a group. | | subscriber.bounced | Fires when an email address bounces. | | subscriber.automation\_triggered | Fires when a subscriber starts an automation. | | subscriber.automation\_completed | Fires when a subscriber finishes an automation. | | subscriber.spam\_reported | Fires when a subscriber marks a campaign as spam. | | subscriber.deleted | Fires when a subscriber is set as deleted or forgotten. The `batchable` option is required for this webhook and must be set as `true`. | | subscriber.active | Fires when a subscriber status is set to active. | | campaign.sent | Fires when a campaign is sent. | | campaign.click | Fires when a subscriber clicks a link in a campaign. The `batchable` option is required for this webhook and must be set as `true`. | | campaign.open | Fires when a subscriber opens a campaign. The `batchable` option is required for this webhook and must be set as `true`. | ## Delivery, attempts and retries [#delivery-attempts-and-retries] Webhooks are only delivered for active accounts. A webhook event is considered delivered when your webserver responds with 2XX status code. Make sure you don't return 4XX or 5XX status codes as part of your business logic, as you will keep getting duplicate webhook events. Your webserver should respond in less than 3 seconds, otherwise webhook is considered failed. For this reason you should not do any heavy processing in the same request cycle and offload it to a different process. Upon failure (timeout or non-2XX status code) webhook events are retried three more times with 10, 100, and finally 1000 seconds delay. ## Security [#security] Webhook requests include `Signature` header, its value is HMAC (sha256) which is generated from payload JSON using webhook's secret. You can check its validity in order to be guaranteed that a request is sent from our side. An example of a function which produces a signature in PHP: ```php public function generateSignature(string $jsonPayload, string $secret): string { return hash_hmac('sha256', $jsonPayload, $secret); } ``` ## List all webhooks [#list-all-webhooks] ```http request GET https://connect.mailerlite.com/api/webhooks ``` ### Response [#response] ``` Response code: 200 OK ``` ```json { "data": [ { "id": "68079566047937883", "name": "Test 2", "url": "http://google.com", "events": [ "subscriber.created" ], "enabled": true, "secret": "ybmcD7PQ9R", "created_at": "2022-10-04 23:22:13", "updated_at": "2022-10-04 23:54:04", "batchable": true }, { "id": "68078863100413274", "name": "Test", "url": "http://google.com", "events": [ "subscriber.created" ], "enabled": true, "secret": "9JVEvb07Yq", "created_at": "2022-10-04 23:11:03", "updated_at": "2022-10-04 23:11:03", "batchable": false }, { "id": "68078820398204249", "name": "Test", "url": "http://google.com", "events": [ "subscriber.created" ], "enabled": true, "secret": "yXIrayUCWJ", "created_at": "2022-10-04 23:10:22", "updated_at": "2022-10-04 23:10:22", "batchable": true }, { "id": "68074372003267924", "name": "Eveniet vero minus.", "url": "http://www.marvin.com/omnis-accusamus-est-rem-delectus-quaerat.html", "events": [ "subscriber.bounced" ], "enabled": true, "secret": "Kn556GohSH", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": false }, { "id": "68074372003267926", "name": "Et voluptatibus et est voluptatibus.", "url": "http://harber.net/ipsa-molestias-voluptatem-fugiat-quis-tempora-ullam.html", "events": [ "subscriber.automation_completed" ], "enabled": true, "secret": "WXS0dF3FHc", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372005365080", "name": "Perferendis dolorem aut nulla.", "url": "http://www.brekke.com/", "events": [ "subscriber.added_to_group" ], "enabled": true, "secret": "Ko17Uw3hiB", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372004316503", "name": "Tenetur delectus eum fugiat.", "url": "http://www.cartwright.info/eligendi-soluta-corporis-in-quod-ullam", "events": [ "subscriber.bounced" ], "enabled": true, "secret": "4jQ3Y4UlLI", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372001170769", "name": "Tempore voluptatem et voluptas.", "url": "http://www.pfeffer.net/quod-voluptatibus-explicabo-nihil-ipsum-accusamus-error", "events": [ "subscriber.removed_from_group" ], "enabled": true, "secret": "hvHGn2D4yu", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372001170770", "name": "Vel inventore rem.", "url": "http://kautzer.com/consequatur-neque-eaque-ad-et-rem-labore-ut.html", "events": [ "subscriber.created" ], "enabled": true, "secret": "xbzp318Djs", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372003267925", "name": "Voluptas animi consequatur.", "url": "http://www.oconner.org/laudantium-ipsa-ad-distinctio-eos-quasi-dicta.html", "events": [ "campaign.sent" ], "enabled": true, "secret": "3b1EMAhuoT", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074371998025039", "name": "Expedita esse est fugit.", "url": "https://www.deckow.com/aut-quae-voluptate-ab-qui-qui", "events": [ "subscriber.removed_from_group" ], "enabled": true, "secret": "QbVgXU0L93", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372000122192", "name": "Autem culpa perferendis quaerat.", "url": "http://homenick.biz/tempora-asperiores-qui-alias-voluptas-eos-necessitatibus-et", "events": [ "subscriber.automation_completed" ], "enabled": true, "secret": "N3cZ5WO2ep", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68074372002219347", "name": "Officia quia aut.", "url": "https://www.cartwright.org/mollitia-corporis-ipsam-reiciendis-dolor-error-amet-velit", "events": [ "subscriber.updated" ], "enabled": true, "secret": "xRyma5WnWP", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": true }, { "id": "68079566047937234", "name": "Campaign Open", "url": "http://google.com", "events": [ "campaign.open" ], "enabled": true, "secret": "ybmcD7PQ9R", "created_at": "2022-10-04 23:22:13", "updated_at": "2022-10-04 23:54:04", "batchable": true }, { "id": "68079566047937324", "name": "Campaign link clicked", "url": "http://google.com", "events": [ "campaign.click" ], "enabled": true, "secret": "ybmcD7PQ9R", "created_at": "2022-10-04 23:22:13", "updated_at": "2022-10-04 23:54:04", "batchable": true }, { "id": "68079566047937325", "name": "Subscriber deleted", "url": "http://google.com", "events": [ "subscriber.deleted" ], "enabled": true, "secret": "ybmcD7PQ9o", "created_at": "2022-10-04 23:22:13", "updated_at": "2022-10-04 23:54:04", "batchable": true }, { "id": "68079566047937321", "name": "Subscriber deleted", "url": "http://google.com", "events": [ "subscriber.active" ], "enabled": true, "secret": "ybmcD7PQ1o", "created_at": "2022-10-04 23:22:13", "updated_at": "2022-10-04 23:54:04", "batchable": false } ], "links": { "first": "http://localhost:8080/api/webhooks?page=1", "last": "http://localhost:8080/api/webhooks?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "http://localhost:8080/api/webhooks?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "http://localhost:8080/api/webhooks", "per_page": 50, "to": 13, "total": 13 } } ``` ## Get a webhook [#get-a-webhook] ```http request GET https://connect.mailerlite.com/api/webhooks/{webhook_id} ``` ### Response [#response-1] ``` Response code: 200 OK ``` ```json { "data": { "id": "68074372004316503", "name": "Tenetur delectus eum fugiat.", "url": "http://www.cartwright.info/eligendi-soluta-corporis-in-quod-ullam", "events": [ "subscriber.bounced" ], "enabled": true, "secret": "4jQ3Y4UlLI", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": false } } ``` ### Error [#error] When providing an invalid webhook id ```http Response code: 404 Not Found ``` ## Create a webhook [#create-a-webhook] ```http request POST https://connect.mailerlite.com/api/webhooks ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | ----------------------------------------------------------------------- | | name | string | no | | | events | array | yes | Must be one of the events described in following table | | url | string | yes | | | enabled | boolean | no | | | batchable | boolean | no | Required as `true` only for `campaign.open` and `campaign.click` events | ### Response [#response-2] ``` Response code: 200 OK ``` ```json { "data": { "id": "68074372004316503", "name": "Tenetur delectus eum fugiat.", "url": "http://www.cartwright.info/eligendi-soluta-corporis-in-quod-ullam", "events": [ "subscriber.bounced" ], "enabled": true, "secret": "4jQ3Y4UlLI", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": false } } ``` ## Update a webhook [#update-a-webhook] ```http request PUT https://connect.mailerlite.com/api/webhooks/{webhook_id} ``` ### Request body [#request-body-1] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | ----------------------------------------------------------------------- | | name | string | no | | | events | array | no | | | url | string | no | | | enabled | boolean | no | | | batchable | boolean | no | Required as `true` only for `campaign.open` and `campaign.click` events | ### Response [#response-3] ``` Response code: 200 OK ``` ```json { "data": { "id": "68074372004316503", "name": "Tenetur delectus eum fugiat.", "url": "http://www.cartwright.info/eligendi-soluta-corporis-in-quod-ullam", "events": [ "subscriber.bounced" ], "enabled": true, "secret": "4jQ3Y4UlLI", "created_at": "2022-10-04 21:59:40", "updated_at": "2022-10-04 21:59:40", "batchable": false } } ``` ## Delete a webhook [#delete-a-webhook] ```http request DELETE https://connect.mailerlite.com/api/webhooks/{webhook_id} ``` ### Response [#response-4] ``` Response code: 204 No Content ``` ## Payloads [#payloads] Examples of webhooks data you can receive `subscriber.created`
Show payload details ```json { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null, "event": "subscriber.created", "account_id": 0 } ```
`subscriber.updated`
Show payload details ```json { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null, "event": "subscriber.updated", "account_id": 0 } ```
`subscriber.unsubscribed`
Show payload details ```json { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null, "event": "subscriber.unsubscribed", "account_id": 0 } ```
`subscriber.added_to_group`
Show payload details ```json { "type": "subscriber.added_to_group", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 1, "clicks_count": 1, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "group": { "id": "100000000000000000", "name": "Group Example" }, "account_id": 0 } ```
`subscriber.removed_from_group`
Show payload details ```json { "type": "subscriber.removed_from_group", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 1, "clicks_count": 1, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "group": { "id": "100000000000000000", "name": "Group Example" }, "account_id": 0 } ```
`subscriber.bounced`
Show payload details ```json { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 1, "clicks_count": 1, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null, "event": "subscriber.bounced", "account_id": 0 } ```
`subscriber.automation_triggered`
Show payload details ```json { "type": "subscriber.automation_triggered", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "automation": { "id": "100000000000000000", "name": "Automation Example" }, "account_id": 0 } ```
`subscriber.automation_completed`
Show payload details ```json { "type": "subscriber.automation_completed", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "automation": { "id": "100000000000000000", "name": "Automation Example" }, "account_id": 0 } ```
`subscriber.spam_reported`
Show payload details ```json { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null, "event": "subscriber.spam_reported", "account_id": 0 } ```
`campaign.sent`
Show payload details ```json { "id": "100000000000000000", "name": "Campaign name", "total_recipients": 1000, "preview_url": "https://dashboard.mailerlite.com/preview/1/emails/100000000000000000", "date": "2024-07-01T01:01:01.000000Z", "event": "campaign.sent", "account_id": 0 } ```
`campaign.open`
Show payload details ```json { "type": "campaign.open", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "campaign": { "id": "100000000000000000", "name": "Campaign Example", "total_recipients": 100, "preview_url": "https://preview_url", "date": "2024-05-28T07:11:08.000000Z" }, "account_id": 0 } ```
`campaign.click`
Show payload details ```json { "type": "campaign.click", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 1, "clicks_count": 1, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "campaign": { "id": "100000000000000000", "name": "Campaign Example", "total_recipients": 100, "preview_url": "https://preview_url", "date": "2024-05-28T07:11:08.000000Z" }, "link_url": "https://your-url.example/example", "account_id": 0 } ```
`subscriber.deleted`
Show payload details ```json { "type": "subscriber.deleted", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 1, "clicks_count": 1, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": "2024-05-28T10:30:29.000000Z", "forget_at": "2024-05-28T10:30:29.000000Z", "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "account_id": 0 } ```
`subscriber.active`
Show payload details ```json { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 1, "clicks_count": 1, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": "2024-05-28T10:30:29.000000Z", "forget_at": "2024-05-28T10:30:29.000000Z", "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null, "account_id": 0, "event": "subscriber.active" } ```
## Batched payloads [#batched-payloads]
Show batched payload details ```json { "events": [ { "type": "campaign.open", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "campaign": { "id": "100000000000000000", "name": "Campaign Example", "total_recipients": 100, "preview_url": "https://preview_url", "date": "2024-05-28T07:11:08.000000Z" } }, { "type": "campaign.open", "subscriber": { "id": "100000000000000000", "email": "john.doe@example.com", "status": "active", "source": "ecommerce", "sent": 5, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2024-05-08T08:26:04.000000Z", "unsubscribed_at": null, "created_at": "2024-05-08T08:26:04.000000Z", "updated_at": "2024-05-28T10:30:29.000000Z", "deleted_at": null, "forget_at": null, "fields": { "name": "", "last_name": "", "company": "", "country": "", "city": "", "phone": "", "state": "", "zip": "" }, "opted_in_at": null, "optin_ip": null }, "campaign": { "id": "100000000000000000", "name": "Campaign Example", "total_recipients": 100, "preview_url": "https://preview_url", "date": "2024-05-28T07:11:08.000000Z" } } ], "total": 2 } ```
# E-commerce Cart Items API (/ecommerce/cart-items) ## Get the items of a cart [#get-the-items-of-a-cart] If you want to get a list items of the given cart, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | cart\_id | integer | yes | Must provide valid cart id | | limit | integer | no | Defaults to `100` | | page | integer | no | Defaults to `1` | ### Response [#response] ```json { "data": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items", "per_page": 100, "to": 1, "total": 1 } } ``` ## Add/update a cart item [#addupdate-a-cart-item] You can add or update a cart item. If you want to create a cart item for a given shop, use this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items ``` If you want to update the cart item for the given shop, use this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items/:item_id ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | ---------------------- | ------- | -------- | ---------------------------------------- | | ecommerce\_product\_id | integer | yes | The id of the product to add to the cart | | variant | string | no | The product's variant information. | | quantity | integer | no | The products quantity. Defaults to `1`. | | price | float | no | The cart item's price. Defaults to `0`. | ``` { "ecommerce_product_id": "64375689754", "price": 123.40, "variant": "Color black, size medium", "quantity": 2, } ``` ### Response [#response-1] If the cart item was created: ```http Response Code: 201 Created ``` ```json { "data": { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "Color black, size medium", "quantity": 2, "price": 123.4 } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "ecommerce_product_id": ["The ecommerce_product_id must be provided."] } } ``` ## Fetch a cart item [#fetch-a-cart-item] If you want to create a cart item, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items/:item_id ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | ------------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | cart\_id | integer | yes | Must provide valid cart id | | item\_id | integer | yes | Must provide valid cart item id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537/carts/319868430643456756/items/34567564567 ``` ### Response [#response-2] If the shop, cart and cart item exist: ```http Response Code: 200 OK ``` ```json { "data": { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "Color black, size medium", "quantity": 2, "price": 123.4 } } ``` #### Error [#error-1] If the shop, cart or cart item cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total cart items count [#fetch-total-cart-items-count] If you want to fetch the total cart items count, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items?limit=0 ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | cart\_id | integer | yes | Must provide valid cart id | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 123 } ``` ## Delete a cart item [#delete-a-cart-item] If you want to delete a cart item, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id/items/:item_id ``` ### Request parameters [#request-parameters-3] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | ------------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | cart\_id | integer | yes | Must provide valid cart id | | item\_id | integer | yes | Must provide valid cart item id | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "data": { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "Color black, size medium", "quantity": 2, "price": 123.4 } } ``` ### Error [#error-2] ``` Response code: 404 Not Found ``` # E-commerce Cart API (/ecommerce/cart) ## Get carts [#get-carts] If you want to get a list of carts for a given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | no | Defaults to `100` | | page | integer | no | Defaults to `1` | ### Response [#response] ```json { "data": [ { "id": "12564435675647", "ecommerce_order_id": "3456678978907", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts", "per_page": 100, "to": 1, "total": 1 } } ``` ## Update a cart [#update-a-cart] If you want to update a cart, please send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id ``` Note: Carts can only be created through the orders endpoint. ### Request body [#request-body] | Parameter | Type | Required | Limitations | | ------------- | ------ | -------- | --------------------------------------------------------------- | | checkout\_url | string | no | The cart's checkout url. | | cart\_total | float | no | The cart's total price in the shop's currency. Defaults to `0`. | ``` { "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, } ``` ### Response [#response-1] If the cart was updated: ```http Response Code: 200 OK ``` ```json { "data": { "id": "12564435675647", "ecommerce_order_id": "3456678978907", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] } } ``` Notes: You can use the respective cart items endpoints to update a cart's items. ## Fetch a cart [#fetch-a-cart] If you want to fetch a cart, please send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts/:cart_id ``` ### Request [#request] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | cart\_id | integer | yes | Must provide valid cart id | | shop\_id | integer | yes | Must provide valid shop id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537/products/319868430643456756 ``` ### Response [#response-2] If the shop and the cart exist: ```http Response Code: 200 OK ``` ```json { "data": { "id": "12564435675647", "ecommerce_order_id": "3456678978907", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] } } ``` #### Error [#error] If the cart or shop cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total carts count [#fetch-total-carts-count] If you want to fetch total carts count, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/carts?limit=0 ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 123 } ``` ## Delete a cart [#delete-a-cart] You cannot delete a cart. A cart is automatically deleted when its associated order gets deleted. # E-commerce Categories Products API (/ecommerce/categories-products) Assign/unassign products to categories ## Get the products of a category [#get-the-products-of-a-category] If you want to get the products for a particular shop and a category, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | category\_id | integer | yes | Must provide category id | | limit | integer | no | Defaults to `100` | | page | integer | no | Defaults to `1` | ### Response [#response] ```json { "data": [ { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products", "per_page": 100, "to": 1, "total": 1 } } ``` ## Assign a product to a category [#assign-a-product-to-a-category] If you want to assign a product to a category for a given shop, send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products/:product_id ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | category\_id | integer | yes | Must provide category id | | product\_id | integer | yes | Must provide product id | ### Response [#response-1] If the product was assigned to the category: ```http Response Code: 200 OK ``` ```json { "data": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "product_id": ["The product id must be provided."] } } ``` ## Unassign a product from a category [#unassign-a-product-from-a-category] If you want to unassign a product from a category for a given shop, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id/products/:product_id ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | category\_id | integer | yes | Must provide category id | | product\_id | integer | yes | Must provide product id | ### Response [#response-2] ``` Response code: 200 OK ``` ```json { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] } ``` ### Error [#error-1] ``` Response code: 404 Not Found ``` # E-commerce Categories API (/ecommerce/categories) ## Get categories [#get-categories] If you want to get all categories of the given shop\_id, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | no | Defaults to `100` | | page | integer | no | Defaults to `1` | ### Response [#response] ```json { "data": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories", "per_page": 100, "to": 1, "total": 1 } } ``` ## Create/update category [#createupdate-category] You can create or update the category of the given shop. If you want to create the category, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories ``` If you want to update the category, send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | -------------------------- | ------- | -------- | --------------------------------------------------------------------------- | | name | string | yes | The category's name | | exclude\_from\_automations | boolean | no | If true this category will not trigger any automations. Defaults to `false` | ``` { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ``` ### Response [#response-1] If the category was created: ```http Response Code: 201 Created ``` ```json { "data": { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "name": ["The name must be provided."] } } ``` ## Fetch a category [#fetch-a-category] If you want to fetch a category for a given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | ------------------------------ | | category\_id | integer | yes | Must provide valid category id | | shop\_id | integer | yes | Must provide valid shop id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537/categories/319868430643456756 ``` ### Response [#response-2] If the shop and the category exist: ```http Response Code: 200 OK ``` ```json { "data": { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } } ``` #### Error [#error-1] If the category or shop cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total categories count [#fetch-total-categories-count] If you want to fetch the count of all categories, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories?limit=0 ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 123 } ``` ## Delete a category [#delete-a-category] If you want to delete a category for the given shop, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/:category_id ``` ### Request parameters [#request-parameters-3] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | ------------------------------ | | category\_id | integer | yes | Must provide valid category id | | shop\_id | integer | yes | Must provide valid shop id | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ``` ### Error [#error-2] ``` Response code: 404 Not Found ``` # E-commerce Customers API (/ecommerce/customers) ## Get customers [#get-customers] If you want to get a list of customers for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | no | Defaults to 100 | | page | integer | no | Defaults to 1 | ### Response [#response] ```json { "data": [ { "id": "31986843064993537", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers", "per_page": 100, "to": 1, "total": 1 } } ``` Notes: The subscriber field will be `null` if no subscriber exists for the customer. ## Create/update customer [#createupdate-customer] You can create or update a customer for the given shop. If you want to create a customer, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers ``` If you want to update the customer, send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers/:customer_id ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | ------------------ | ------- | -------- | -------------------------------------------------------------- | | email | string | yes | Customer's email address | | accepts\_marketing | boolean | no | True if the customer accepts marketing emails, false otherwise | | total\_spent | float | no | The total amount the customer has spent in the shop. | | create\_subscriber | boolean | no | If set, a subscriber will be created for the customer. | ``` { "email": "Customer name", "accepts_marketing": true, "total_spent": 1234.99 "create_subscriber": true, } ``` ### Response [#response-1] If the customer was created: ```http Response Code: 201 Created ``` ```json { "data": { "id": "31986843064993537", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } } ``` Notes: The subscriber field will be `null` if no subscriber exists for the customer. If a subscriber exists with the same email as the customer, the customer will be associated with that subscriber. Doing a `PUT` request with `create_subscriber` set to `false` on a customer that has a subscriber associated, has no effect. Doing a `PUT` request with `create_subscriber` set to `true` on a customer that doesn't have a subscriber, creates the subscriber. #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "email": ["The email must be provided."] } } ``` ## Fetch a customer [#fetch-a-customer] If you want to fetch a customer for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers/:customer_id ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | ------------------------------ | | customer\_id | integer | yes | Must provide valid customer id | | shop\_id | integer | yes | Must provide valid shop id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537/customers/319868430643456756 ``` ### Response [#response-2] If the shop and the customer exist: ```http Response Code: 200 OK ``` ```json { "data": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } } } ``` Notes: The subscriber field will be `null` if no subscriber exists for the customer. #### Error [#error-1] If the customer or shop cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total customers count [#fetch-total-customers-count] If you want to fetch total customers count for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers?limit=0 ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 123 } ``` ## Delete a customer [#delete-a-customer] If you want to delete a customer for the given shop, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/customers/:customer_id ``` ### Request parameters [#request-parameters-3] | Parameter | Type | Required | Limitations | | ------------ | ------- | -------- | ------------------------------ | | customer\_id | integer | yes | Must provide valid customer id | | shop\_id | integer | yes | Must provide valid shop id | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "data": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } } } ``` Notes: The subscriber field will be `null` if no subscriber exists for the customer. If a subscriber is associated with the customer, the subscriber will not be deleted or affected. ### Error [#error-2] ``` Response code: 404 Not Found ``` # E-commerce Import API (/ecommerce/import) You can bulk import categories, products and orders to the platform. ## Categories import [#categories-import] If you want to import multiple categories for the given shop, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/categories/import ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | ``` [ { "name": "Category 1", "exclude_from_automations": false }, { "name": "Category 2", "exclude_from_automations": false } ] ``` ### Response [#response] If the categories were created: ```http Response Code: 200 OK ``` ```json { "data": [ { "id": 46919150796276752, "name": "Category 1", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" }, { "id": 46919150798373905, "name": "Category 2", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" } ] } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "0.name": ["The name field is required."] } } ``` ## Products import [#products-import] If you want to import products for the given shop, use this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products/import ``` ### Request body [#request-body-1] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | ``` [ { "name": "Product name", "price": 123.40, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ 46919150796276752, 46919150798373905 ] }, { "name": "Product 2 name", "price": 123.40, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ 46919150796276752, 46919150798373905 ] } ] ``` ### Response [#response-1] If the products were created: ```http Response Code: 200 OK ``` ```json { "data": [ { "id": 46920297804203043, "name": "Product name", "price": 123.4, "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": 46919150796276752, "name": "Category 1", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" }, { "id": 46919150798373905, "name": "Category 2", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" } ] }, { "id": 46920297809445924, "name": "Product 2 name", "price": 123.4, "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": 46919150796276752, "name": "Category 1", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" }, { "id": 46919150798373905, "name": "Category 2", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" } ] } ] } ``` #### Error [#error-1] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "0.name": ["The name field is required."] } } ``` ## Orders import [#orders-import] If you want to import orders including customers, carts and cart items for the given shop, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders/import ``` ### Request body [#request-body-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | ``` [ { "customer": { "email": "customer@email.com", "create_subscriber": true, "accepts_marketing": true }, "cart": { "items": [ { "ecommerce_product_id": "46920297804203043", "variant": "product variant", "quantity": 1, "price": 123.40 } ] }, "status": "pending", "total_price": 123.40 }, { "customer": { "email": "customer2@email.com", "create_subscriber": true, "accepts_marketing": true }, "cart": { "items": [ { "ecommerce_product_id": "46920297804203043", "variant": "product variant", "quantity": 1, "price": 123.40 } ] }, "status": "pending", "total_price": 123.40 } ] ``` ### Response [#response-2] If the orders were created: ```http Response Code: 200 OK ``` ```json { "data": [ { "id": 46920756608631854, "customer": { "id": 46920756260504617, "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "46920756366410794", "email": "customer@email.com", "status": "active", "source": "manual", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2022-02-13 10:12:00", "unsubscribed_at": null, "created_at": "2022-02-13 10:12:00", "updated_at": "2022-02-13 10:12:00", "opted_in_at": null, "optin_ip": null } }, "cart": { "id": 46920756586611756, "checkout_url": null, "cart_total": "0", "items": [ { "id": 46920756598146093, "product": { "id": 46920297804203043, "name": "Product name", "price": "123.4", "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": 46919150796276752, "name": "Category 1", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" }, { "id": 46919150798373905, "name": "Category 2", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" } ] }, "variant": "product variant", "quantity": 1, "price": "123.4" } ] }, "total": 123.4, "status": "pending", "created_at": "2022-02-13T10:12:00.000000Z", "updated_at": "2022-02-13T10:12:00.000000Z" }, { "id": 46920756705100851, "customer": { "id": 46920756614923311, "email": "customer2@email.com", "accepts_marketing": true, "subscriber": { "id": "46920756639040560", "email": "customer2@email.com", "status": "active", "source": "manual", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2022-02-13 10:12:00", "unsubscribed_at": null, "created_at": "2022-02-13 10:12:00", "updated_at": "2022-02-13 10:12:00", "opted_in_at": null, "optin_ip": null } }, "cart": { "id": 46920756693566513, "checkout_url": null, "cart_total": "0", "items": [ { "id": 46920756700906546, "product": { "id": 46920297804203043, "name": "Product name", "price": "123.4", "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": 46919150796276752, "name": "Category 1", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" }, { "id": 46919150798373905, "name": "Category 2", "exclude_from_automations": false, "created_at": "2022-02-13T09:46:29.000000Z", "updated_at": "2022-02-13T09:46:29.000000Z" } ] }, "variant": "product variant", "quantity": 1, "price": "123.4" } ] }, "total": 123.4, "status": "pending", "created_at": "2022-02-13T10:12:00.000000Z", "updated_at": "2022-02-13T10:12:00.000000Z" } ] } ``` #### Error [#error-2] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "0.customer": ["The 0.customer field is required."] } } ``` # E-commerce Orders API (/ecommerce/orders) ## Get orders [#get-orders] If you want to get orders for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders ``` Get a list of orders for the given shop. ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | no | Defaults to 100 | | page | integer | no | Defaults to 1 | ### Response [#response] ```json { "data": [ { "id": "31986843064993537", "shop": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "cart": { "id": "12564435675647", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] }, "total": 123.4, "status": "pending", "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders", "per_page": 100, "to": 1, "total": 1 } } ``` ## Create/update order [#createupdate-order] You can create or update an order for the given shop. If you want to create an order for the given shop, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders ``` If you want to update an order for the given shop, send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders/:order_id ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | ------------ | ------ | -------- | ------------------------------------------------------------------------------------ | | customer | array | yes | The customer information. Check the respective ecommerce customer api documentation. | | cart | array | yes | The order cart. Check the respective ecommerce cart api documentation. | | status | string | no | The order's status. Allowed values: `pending`, `complete`. Defaults to `pending`. | | total\_price | float | no | The order's total price. Defaults to `0`. | ``` { "customer": { "email": "customer@email.com", "create_subscriber": true, "accepts_marketing": true }, "cart": { "items": [ { "ecommerce_product_id": "1236545467567", "variant": "product variant", "quantity": 1, "price": 123.40 } ] }, "status": "pending", "total_price": 123.40 } ``` Notes: The customer will be created if a customer with the same email doesn't already exist in the platform. You cannot update the `cart` or the `customer` of an order through the `PUT` endpoint. You'll have to use the respective `Customer` and `Cart` endpoints instead. ### Response [#response-1] If the order was created: ```http Response Code: 201 Created ``` ```json { "data": { "id": "31986843064993537", "shop": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "cart": { "id": "12564435675647", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] }, "total": 123.4, "status": "pending", "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "customer": ["The customer must be provided."] } } ``` ## Fetch an order [#fetch-an-order] If you want to fetch an order for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders/:order_id ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | --------------------------- | | order\_id | integer | yes | Must provide valid order id | | shop\_id | integer | yes | Must provide valid shop id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537/orders/319868430643456756 ``` ### Response [#response-2] If the shop and the order exist: ```http Response Code: 200 OK ``` ```json { "data": { "id": "31986843064993537", "shop": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "cart": { "id": "12564435675647", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] }, "total": 123.4, "status": "pending", "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } } ``` #### Error [#error-1] If the order or shop cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total orders count [#fetch-total-orders-count] If you want to fetch total orders count for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders?limit=0 ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 123 } ``` ## Delete an order [#delete-an-order] If you want to delete an order, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/orders/:order_id ``` ### Request parameters [#request-parameters-3] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | --------------------------- | | order\_id | integer | yes | Must provide valid order id | | shop\_id | integer | yes | Must provide valid shop id | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "data": { "id": "31986843064993537", "shop": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, "customer": { "id": "319868430643456756", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "31986843064993537", "email": "customer@email.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-09-01 14:03:50", "unsubscribed_at": null, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "fields": { "city": null, "company": null, "country": null, "last_name": "Testerson", "name": "Dummy", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } }, "cart": { "id": "12564435675647", "checkout_url": "https://url-to-cart-checkout.com", "cart_total": 1234.99, "items": [ { "id": "45676855678345", "product": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] }, "variant": "product variant", "quantity": 1, "price": 123.4 } ] }, "total": 123.4, "status": "pending", "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } } ``` Notes: Deleting an order will also delete the associated cart and cart items. ### Error [#error-2] ``` Response code: 404 Not Found ``` # E-commerce Products API (/ecommerce/products) ## Get products [#get-products] If you want to get products for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | no | Defaults to `100` | | page | integer | no | Defaults to `1` | ### Response [#response] ```json { "data": [ { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "short_description": "Product's short description.", "description": "Product's longer description.", "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products", "per_page": 100, "to": 1, "total": 1 } } ``` ## Create/update product [#createupdate-product] You can create or update a product for the given shop. To create a product for the given shop, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products ``` To update a product for the given shop, send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products/:product_id ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | -------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | | name | string | yes | The product's name | | price | float | no | The product's price in the shop's currency. Defaults to `0`. | | exclude\_from\_automations | boolean | no | If true this product will not trigger any automations. Defaults to `false` | | url | string | no | The products url. | | image | string | no | The products main image url. | | short\_description | string | no | The product's short description. Max `255` characters. HTML tags are automatically removed | | description | string | no | The product's description. HTML tags are automatically removed. | ``` { "name": "Product name", "price": 123.40, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "short_description": "Product's short description.", "description": "Product's longer description." } ``` ### Response [#response-1] If the product was created: ```http Response Code: 201 Created ``` ```json { "data": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "short_description": "Product's short description.", "description": "Product's longer description.", "categories": [] } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "name": ["The name must be provided."] } } ``` ## Fetch a product [#fetch-a-product] If you want to fetch a product for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products/:product_id ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | ----------- | ------- | -------- | ----------------------------- | | product\_id | integer | yes | Must provide valid product id | | shop\_id | integer | yes | Must provide valid shop id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537/products/319868430643456756 ``` ### Response [#response-2] If the shop and the product exist: ```http Response Code: 200 OK ``` ```json { "data": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "short_description": "Product's short description.", "description": "Product's longer description.", "categories": [ { "id": "1234566457534276", "name": "Category 1", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" }, { "id": "1234566457534278", "name": "Category 2", "exclude_from_automations": false, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50" } ] } } ``` #### Error [#error-1] If the product or shop cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total products count [#fetch-total-products-count] If you want to fetch the total products count for the given shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products?limit=0 ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------------------- | | shop\_id | integer | yes | Must provide valid shop id | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 123 } ``` ## Delete a product [#delete-a-product] If you want to delete a product for the given shop, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:shop_id/products/:product_id ``` ### Request parameters [#request-parameters-3] | Parameter | Type | Required | Limitations | | ----------- | ------- | -------- | ----------------------------- | | product\_id | integer | yes | Must provide valid product id | | shop\_id | integer | yes | Must provide valid shop id | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "data": { "id": "31986843543567834", "name": "Product name", "price": 123.4, "url": "https://shop-url.com/product-name", "image": "https://shop-url.com/product-image.jpg", "exclude_from_automations": false, "short_description": "Product's short description.", "description": "Product's longer description.", "categories": [] } } ``` ### Error [#error-2] ``` Response code: 404 Not Found ``` # E-commerce API (/ecommerce/shops) MailerLite E-commerce API allows to connect an external shop to your MailerLite account. E-commerce API endpoints enable additional MailerLite features such as E-commerce Automation (abandoned cart automations, post-purchase emails, etc.), product import into your newsletters, sales tracking and more. ## List e-commerce shops [#list-e-commerce-shops] If you want to get a list of all available shops connected to your account, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops ``` ### Request parameters [#request-parameters] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | -------------- | | limit | integer | no | Defaults to 50 | | page | integer | no | Defaults to 1 | ### Response [#response] ```json { "data": [ { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "currency_sign": "$" } ], "links": { "first": "https://connect.mailerlite.com/api/ecommerce/shops?page=1", "last": "https://connect.mailerlite.com/api/ecommerce/shops?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/ecommerce/shops?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/ecommerce/shops", "per_page": 50, "to": 1, "total": 1 } } ``` ## Create/update shop [#createupdate-shop] You can create or update a shop. To create a shop, send this `POST` request ```http POST https://connect.mailerlite.com/api/ecommerce/shops ``` To update a shop, send this `PUT` request ```http PUT https://connect.mailerlite.com/api/ecommerce/shops/(:shop_id) ``` ### Request body [#request-body] | Parameter | Type | Required | Limitations | | -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | yes | Shop name | | url | string | yes | Shop URL address | | currency | string | yes | ISO 4217 currency code that the shop uses. | | platform | string | no | The platform of the shop (e.g. shopify) | | group\_id | integer | no | The id of the group that the shop's subscribers are automatically added to. | | enable\_popups | boolean | no | Enables popups to the shop (the shop must have the universal script added to it). Defaults to `false`. | | enabled | boolean | no | Enable/disable the ecommerce functionality for the shop. Defaults to `false`. | | access\_data | string | no | Platform specific information for the platform to access the shop (e.g. shopify access token or woocommerce keys). Shouldn't be needed for third party users. | ``` { "name": "shop name", "url": "https://shop-url.com", "currency": "EUR", "group_id": 1234567890, "enable_popups": false, "enabled": true } ``` ### Response [#response-1] If the shop was created: ```http Response Code: 201 Created ``` ```json { "data": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "currency_sign": "$" } } ``` #### Error [#error] ```http Response Code: 422 Unprocessable Entity ``` The error response will contain information about the invalid data. ```json { "message": "The given data was invalid.", "errors": { "url": ["The shop url must be provided."] } } ``` ## Fetch a shop [#fetch-a-shop] To fetch a shop, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops/(:shop_id) ``` ### Request parameters [#request-parameters-1] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | --------------------------------- | | id | integer | yes | Must provide either valid shop id | ``` GET https://connect.mailerlite.com/api/ecommerce/shops/31986843064993537 ``` ### Response [#response-2] If shop exists: ```http Response Code: 200 OK ``` ```json { "data": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "currency_sign": "$" } } ``` #### Error [#error-1] If the shop cannot be found: ```http Response Code: 404 Not Found ``` ## Fetch total shops count [#fetch-total-shops-count] If you want to fetch total shops count, send this `GET` request ```http GET https://connect.mailerlite.com/api/ecommerce/shops?limit=0 ``` ### Request parameters [#request-parameters-2] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | --------------- | | limit | integer | yes | Value must be 0 | ### Response [#response-3] ``` Response Code: 200 OK ``` ```json { "total": 100 } ``` ## Delete a shop [#delete-a-shop] If you want to delete a shop, send this `DELETE` request ```http DELETE https://connect.mailerlite.com/api/ecommerce/shops/:id ``` ### Request [#request] | Parameter | Type | Required | Limitations | | --------- | ------- | -------- | ----------------------------- | | id | integer | yes | Valid shop id for the account | ### Response [#response-4] ``` Response code: 200 OK ``` ```json { "data": { "id": "31986843064993537", "name": "shop name", "url": "https://shop-url.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": { "id": "1", "name": "dummy group", "total": 20, "open_rate": { "float": 0, "string": "0%" }, "click_rate": { "float": 0, "string": "0%" }, "created_at": "2021-08-06 10:17:45" }, "created_at": "2021-09-01 14:03:50", "updated_at": "2021-09-01 14:03:50", "currency_sign": "$" } } ``` ### Error [#error-2] ``` Response code: 404 Not Found ``` # Basic integrations (/guides/basic) Create a connection between your selected service and MailerLite. We are always open to new integrations with other viable products using our API. If you have created one or are interested in creating an integration, feel free to share it with us by [this dedicated contact form](https://www.mailerlite.com/integrations/submit). ## Getting started [#getting-started] Before we begin, please familiarize yourself with the general [API conventions](/getting-started#getting-started), limits, and terms of service. Our API is extremely intuitive, so understanding how it works shouldn't take long if you've used a RESTful HTTP API before. You will also need to authenticate your requests to our API. You can find out how to do that [here](/getting-started#authentication). For the purposes of this guide, we’ll use the example of a virtual book club. We want to integrate our custom website with our account on MailerLite. ## Syncing subscribers [#syncing-subscribers] Let's say our clients can select "Get weekly newsletter" when signing up for a website membership. Once the client signs up and confirms their email address, we can sync them to MailerLite using POST [/api/subscribers](/api/subscribers#create-upsert-subscriber) endpoint. **Request:** ```http POST connect.mailerlite.com/api/subscribers ``` ```json { "email": "john@example.com", "fields": { "name": "John", "last_name": "Wick" } } ``` **Response:** ```json { "data": { "id": "31897397363737859", "email": "john@example.com", "status": "active", "source": "api", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2021-08-31 14:22:08", "unsubscribed_at": null, "created_at": "2021-08-31 14:22:08", "updated_at": "2021-08-31 14:22:08", "fields": { "city": null, "company": null, "country": null, "last_name": "Wick", "name": "John", "phone": null, "state": null, "z_i_p": null }, "groups": [], "opted_in_at": null, "optin_ip": null } } ``` Pro tip: it can be a good idea to store the MailerLite subscriber id (in this case `31897397363737859`) as an attribute of the client in your system. This will make further API calls much easier. If the subscriber already exists in your mailing list, they will be updated with the newest field values. If we want to let our clients select specific interests, we can use separate checkboxes for "True crime", "Romance", "Biographies" etc. and add them to groups accordingly. **Request:** ```json { "email": "john@example.com", "fields": { "name": "John", "last_name": "Wick" }, "groups": [ "4243829086487936", // ID for True crime group "14133878422767533" // ID for Romance group ] } ``` You can find the group ids [listed here](https://dashboard.mailerlite.com/integrations/api) and use them as constants in your implementation. Alternatively, you can fetch groups interactively from `GET /api/groups` endpoint and optionally provide a `filter[name]` parameter to search groups by name. **Request:** ```http GET connect.mailerlite.com/api/groups?filter[name]=Romance ``` **Response:** ```json { "data": [ { "id": "14133878422767533", "name": "Romance", "active_count": 256, "sent_count": 124, "opens_count": 62, "open_rate": { "float": 0.5, "string": "50%" }, "clicks_count": 62, "click_rate": { "float": 0.5, "string": "50%" }, "unsubscribed_count": 0, "unconfirmed_count": 0, "bounced_count": 0, "junk_count": 0, "created_at": "2022-05-24 11:52:55" } ], "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "https://connect.mailerlite.com/api/groups?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "https://connect.mailerlite.com/api/groups", "per_page": 100, "to": 1, "total": 1 } } ``` ## Removing subscribers from groups [#removing-subscribers-from-groups] Suppose our client went into their profile and unchecked the checkbox for "Romance recommendations". We need to respect their choice and remove the subscriber from the group. If you followed advice and stored subscriber id as a client attribute, this will be super simple. **Request:** ```http DELETE https://connect.mailerlite.com/api/subscribers/31897397363737859/groups/14133878422767533 ``` **Response:** ```http Response Code: 204 No Content ``` If you didn't follow the advice and don't have the subscriber id at hand (you rebel!), you could provide an email address instead. **Request:** ```http DELETE https://connect.mailerlite.com/api/subscribers/john@example.com/groups/14133878422767533 ``` **Response:** ```http Response Code: 204 No Content ``` Mind you, this is not recommended, as subscribers can change their email address through subscriber [preference center](https://www.mailerlite.com/help/how-to-use-the-preference-center) and thus use a different email address from your records. Only use this in a pinch. ## Adding subscribers to groups [#adding-subscribers-to-groups] Suppose the opposite happens and the client chooses to receive "Romance recommendations" after they've already signed up. **Request:** ```http POST https://connect.mailerlite.com/api/subscribers/31897397363737859/groups/14133878422767533 ``` **Response:** ```http Response Code: 204 No Content ``` ## Remove subscribers [#remove-subscribers] Let's say our client deleted their profile in our book club and requested to be removed from all mailing lists completely. It's not pleasant to say goodbye, but at least it's not complicated. **Request:** ```http DELETE https://connect.mailerlite.com/api/subscribers/31897397363737859 ``` **Response:** ```http Response Code: 200 Ok ``` # E-commerce integrations (/guides/ecommerce) One of the many powerful features of MailerLite is the ability to connect any e-commerce shop with the platform, enabling users to take advantage of features such as e-commerce automations and e-commerce campaign tracking. Integration with any e-commerce platform can be made with a few simple API calls, allowing easy syncing of the shop’s products, categories, orders and customers. ## Getting started [#getting-started] Before we begin, please familiarize yourself with the general [API conventions](/getting-started#getting-started), limits, and terms of service. Our API is extremely intuitive, so it shouldn't take you long if you've ever used a RESTful HTTP API before. You will also need to authenticate your requests to our API. You can find out how to do that [here](/getting-started#authentication). For the purposes of this article, we’ll use the example of a webshop selling t-shirts located at [www.superamazingtshirts.com](http://www.superamazingtshirts.com). We want to integrate our shop with our account on MailerLite. ## Create a shop [#create-a-shop] First, we need to do a simple POST request to the MailerLite API to create a record for our shop: ``` POST connect.mailerlite.com/api/ecommerce/shops ``` ```json { "name": "Super Amazing T-Shirts", "url": "superamazingtshirts.com", "currency": "USD", "enabled": true } ``` The above will give us the following response: ```json { "data": { "id": "134", "name": "Super Amazing T-Shirts", "url": "superamazingtshirts.com", "currency": "USD", "enabled": true, "enable_popups": null, "group": null, "created_at": "2022-04-10T15:24:56.000000Z", "updated_at": "2022-04-10T15:24:56.000000Z", "currency_sign": "$" } } ``` We need to note down the shop’s ID, as we will use it in all of our subsequent API calls. ## Syncing categories and products [#syncing-categories-and-products] Syncing categories and products into MailerLite allows you to create e-commerce automations that are triggered when a specific product, or a product from a specific category, is purchased. In our Super Amazing T-Shirts case, we would like to trigger an automation when a user purchases from our Superdeals category; more on that later. We want to import all of our categories first, so we are going to use the respective e-commerce categories import API to add them all in one request ``` POST connect.mailerlite.com/api/ecommerce/shops/134/categories/import ``` ```json [ { "name": "Superdeals", "exclude_from_automations": false }, { "name": "Single color", "exclude_from_automations": false }, { "name": "Pattern", "exclude_from_automations": false }, { "name": "Music", "exclude_from_automations": false } ] ``` This will give us the following response: ```json { "data": [ { "id": "52014320214607713", "resource_id": null, "name": "Superdeals", "exclude_from_automations": false, "created_at": "2022-04-10T15:32:01.000000Z", "updated_at": "2022-04-10T15:32:01.000000Z" }, { "id": "52014320218802018", "resource_id": null, "name": "Single color", "exclude_from_automations": false, "created_at": "2022-04-10T15:32:01.000000Z", "updated_at": "2022-04-10T15:32:01.000000Z" }, { "id": "52014320221947747", "resource_id": null, "name": "Pattern", "exclude_from_automations": false, "created_at": "2022-04-10T15:32:01.000000Z", "updated_at": "2022-04-10T15:32:01.000000Z" }, { "id": "52014320225093476", "resource_id": null, "name": "Music", "exclude_from_automations": false, "created_at": "2022-04-10T15:32:01.000000Z", "updated_at": "2022-04-10T15:32:01.000000Z" } ] } ``` Now we have to store and keep track of all the IDs of the imported categories, so we can reference them when creating the products. For simple e-shops with only a few products, this method is fine but for more complex datasets, it will be a problem. Instead you can use resource IDs, which is another name for Bring Your Own IDs. This allows you to set the ID of each resource (such as category, product, order, cart, cart item, customer) and reference a resource using the ID you specified instead of the ID that the platform assigned to it. Let’s do the same categories import but this time using resource IDs: ``` POST connect.mailerlite.com/api/ecommerce/shops/134/categories/import?with_resource_id ``` ```json [ { "resource_id": "cat-superdeals", "name": "Superdeals", "exclude_from_automations": false }, { "resource_id": "cat-single-color", "name": "Single color", "exclude_from_automations": false }, { "resource_id": "cat-pattern", "name": "Pattern", "exclude_from_automations": false }, { "resource_id": "cat-music", "name": "Music", "exclude_from_automations": false } ] ``` As you can see, using resource IDs is dead simple. All you have to do is set the `with_resource_id` flag in your url and pass the resource ID for each category. The resource ID can be anything you like—it is set and managed by you. In our WooCommerce and Shopify integrations, for example, the resource IDs are the IDs of the categories, products, etc. that each platform assigns respectively. The above call will return a similar response to the one we got previously: ```json { "data": [ { "id": "52014701898368045", "resource_id": "cat-superdeals", "name": "Superdeals", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" }, { "id": "52014701903610926", "resource_id": "cat-single-color", "name": "Single color", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" }, { "id": "52014701909902383", "resource_id": "cat-pattern", "name": "Pattern", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" }, { "id": "52014701915145264", "resource_id": "cat-music", "name": "Music", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } ] } ``` A final note about resource IDs is that you can access each resource using its resource ID if you pass the `with_resource_id` flag. For example, to get the Superdeals category using the system assigned ID, we would do the following request ``` GET connect.mailerlite.com/api/ecommerce/shops/134/categories/52014701898368045 ``` To get the same category using its resource ID, we would do the following request ``` GET connect.mailerlite.com/api/ecommerce/shops/134/categories/cat-superdeals?with_resource_id ``` In both cases we will get the exact same response: ```json { "data": { "id": "52014701898368045", "resource_id": "cat-superdeals", "name": "Superdeals", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } } ``` Using resource IDs, there’s no need to keep track of two sets of IDs for your data. You can use the IDs of your e-shop directly in MailerLite. For the rest of the article, we will stick to using resource IDs exclusively. Let’s import a couple products using resource IDs: ``` POST connect.mailerlite.com/api/ecommerce/shops/134/products/import?with_resource_id ``` ```json [ { "resource_id": "prod-tshirt1", "name": "T-Shirt 1", "categories": [ "cat-superdeals", "cat-pattern" ], "price": 20, "exclude_from_automations": false }, { "resource_id": "prod-tshirt2", "name": "T-Shirt 2", "categories": [ "cat-single-color" ], "price": 20, "exclude_from_automations": false } ] ``` Notice that when using the `with_resource_id` flag, all IDs are resource IDs. In this case, we are using the resource IDs that we defined for the categories. We will get the following response for the products import: ```json { "data": [ { "id": "52015833343329937", "name": "T-Shirt 1", "resource_id": "prod-tshirt1", "price": 20, "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": "52014701898368045", "resource_id": "cat-superdeals", "name": "Superdeals", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" }, { "id": "52014701909902383", "resource_id": "cat-pattern", "name": "Pattern", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } ] }, { "id": "52015833348572818", "name": "T-Shirt 2", "resource_id": "prod-tshirt2", "price": 20, "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": "52014701903610926", "resource_id": "cat-single-color", "name": "Single color", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } ] } ] } ``` We can import any existing orders if we want, but let’s assume that our e-shop is new and has no orders yet. ## Creating orders [#creating-orders] When a customer places an order on your shop, we can register it with MailerLite using the following request ``` POST connect.mailerlite.com/api/ecommerce/shops/134/orders?with_resource_id ``` ```json { "resource_id": "new-order1", "customer": { "resource_id": "customer1", "email": "customer@email.com", "create_subscriber": true, "accepts_marketing": true }, "cart": { "resource_id": "cart1", "items": [ { "resource_id": "cart-item1", "product_resource_id": "prod-tshirt1", "quantity": 1, "price": 20 } ] }, "status": "pending", "total_price": 20 } ``` Notice that we are using resource IDs for the order, customer, cart and cart item. We will use these resource IDs to reference them in future requests. And we’ll get the following response: ```json { "data": { "id": "52016443246511136", "resource_id": "new-order1", "customer": { "id": "52016278146123709", "resource_id": "customer1", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "52016278181775299", "email": "customer@email.com", "status": "active", "source": "ecommerce", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2022-04-10 16:03:08", "unsubscribed_at": null, "created_at": "2022-04-10 16:03:08", "updated_at": "2022-04-10 16:03:08", "opted_in_at": null, "optin_ip": null } }, "cart": { "id": "52016443227636766", "checkout_url": null, "cart_total": "0", "items": [ { "id": "52016443234976799", "resource_id": "cart-item1", "product": { "id": "52015669709899317", "name": "T-Shirt 1", "resource_id": "prod-tshirt1", "price": "20", "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": "52014701898368045", "resource_id": "cat-superdeals", "name": "Superdeals", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" }, { "id": "52014701909902383", "resource_id": "cat-pattern", "name": "Pattern", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } ] }, "variant": null, "quantity": 1, "price": "20" } ] }, "total": 20, "status": "pending", "created_at": "2022-04-10T16:05:45.000000Z", "updated_at": "2022-04-10T16:05:45.000000Z" } } ``` When you submit an order to MailerLite with status pending, any abandoned cart automation that you have set up will be triggered. For this reason, you should submit the pending order as soon as you have enough information about the customer (e.g. the customer’s email and marketing preferences). Let’s now say that the user adds another item to the cart. We cannot use the Order API to update the items of the order—we’ll have to use the cart items API: ``` POST connect.mailerlite.com/api/ecommerce/shops/134/carts/cart1/items?with_resource_id ``` ```json { "resource_id": "cart-item2", "product_resource_id": "prod-tshirt2", "quantity": 1, "price": 20 } ``` The above request will add the item to our cart. ## Finishing the order [#finishing-the-order] To mark the order as complete and trigger the e-commerce automations, all we have to do is call the respective endpoint: ``` PUT connect.mailerlite.com/api/ecommerce/shops/134/orders/new-order1?with_resource_id ``` ```json { "status": "complete" } ``` And we will get the order object as a response: ```json { "data": { "id": "52016443246511136", "resource_id": "new-order1", "shop": { "id": "134", "name": "Super Amazing T-Shirts", "url": "superamazingtshirts.com", "currency": "USD", "enabled": true, "enable_popups": false, "group": null, "created_at": "2022-04-10T15:24:56.000000Z", "updated_at": "2022-04-10T15:24:56.000000Z", "currency_sign": "$" }, "customer": { "id": "52016278146123709", "resource_id": "customer1", "email": "customer@email.com", "accepts_marketing": true, "subscriber": { "id": "52016278181775299", "email": "customer@email.com", "status": "active", "source": "ecommerce", "sent": 0, "opens_count": 0, "clicks_count": 0, "open_rate": 0, "click_rate": 0, "ip_address": null, "subscribed_at": "2022-04-10 16:03:08", "unsubscribed_at": null, "created_at": "2022-04-10 16:03:08", "updated_at": "2022-04-10 16:03:08", "opted_in_at": null, "optin_ip": null } }, "cart": { "id": "52016443227636766", "checkout_url": null, "cart_total": "0", "items": [ { "id": "52016443234976799", "resource_id": "cart-item1", "product": { "id": "52015669709899317", "name": "T-Shirt 1", "resource_id": "prod-tshirt1", "price": "20", "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": "52014701898368045", "resource_id": "cat-superdeals", "name": "Superdeals", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" }, { "id": "52014701909902383", "resource_id": "cat-pattern", "name": "Pattern", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } ] }, "variant": null, "quantity": 1, "price": "20" }, { "id": "52016782600308050", "resource_id": "cart-item2", "product": { "id": "52015669714093622", "name": "T-Shirt 2", "resource_id": "prod-tshirt2", "price": "20", "url": null, "image": null, "exclude_from_automations": false, "categories": [ { "id": "52014701903610926", "resource_id": "cat-single-color", "name": "Single color", "exclude_from_automations": false, "created_at": "2022-04-10T15:38:05.000000Z", "updated_at": "2022-04-10T15:38:05.000000Z" } ] }, "variant": null, "quantity": 1, "price": "20" } ] }, "total": "20", "status": "complete", "created_at": "2022-04-10T16:05:45.000000Z", "updated_at": "2022-04-10T16:14:32.000000Z" } } ``` Notice that the sum of the product prices doesn’t equal the order total. That’s because MailerLite doesn’t make any assumptions about the pricing of your store. You might charge tax, shipping and handling fees, or give discounts to your customers. You will have to update the order total by making a PUT request on the same endpoint. You can even set the status to complete and update the total in the same call: ``` PUT connect.mailerlite.com/api/ecommerce/shops/134/orders/new-order1?with_resource_id ``` ```json { "status": "complete", "total_price": 40 } ``` Setting the status of an order to complete will trigger any purchase e-commerce automations we might have and cancel any triggered abandoned cart ones. ## Adding products into campaign emails [#adding-products-into-campaign-emails] Any product that is added into MailerLite can easily be added to campaigns. All you have to do is add any of the product blocks from the e-commerce integration section of the builder into the email, select the block and click the Add products from your store button. You can then select any of your added products and they will be placed into the email, images and all. ## E-commerce campaign tracking [#e-commerce-campaign-tracking] If you send a campaign with e-commerce link tracking enabled, you can track which orders the campaign generated in your shop. For this to work, you need to include the MailerLite universal JavaScript code in all pages of your shop: ```js {/* MailerLite Universal */} {/* End MailerLite Universal */} ``` If you have set up MailerLite embedded forms or pop-ups in your website, you should already have this JavaScript snippet added in your pages. Now when you send a campaign with e-commerce link tracking enabled and direct customers to your shop, the universal script will track any purchases made by those customers, allowing you to view the effectiveness of your campaigns to generate revenue. # Introduction (/guides) MailerLite is an intuitive email marketing solution for people of all skill levels. The key principle behind our solution is simplicity. We provide our customers with an easy-to-use content editor, simplified subscriber management and campaign reports highlighting the most important statistics. We already offer integrations with popular products like WordPress, Zapier, Shopify, WooCommerce, PrestaShop, WordPress, MailerCheck, Sumo, OptinMonster, Privy, CreateForm, SendOwl, and more. However, if the product you're using doesn't have an official integration, you can still use our flexible API to connect to MailerLite. # Examples (/mcp/examples) These are starting points, not a fixed menu — phrase requests in your own words and the assistant will pick the right tools. Prompts marked `[ACTION]` make changes to your account (creating, scheduling, importing); the rest are read-only questions. Depending on your client, you may need to refine your wording to trigger the right tools. *** #### Campaigns & Newsletters [#campaigns--newsletters] Your AI assistant can be your ghostwriter, data analyst, and scheduler all in one. **Analytics & Insights:** * "Rank my last 10 campaigns by open and click rate, and tell me what the top performers have in common." * "Identify my top 3 performing newsletters from the last quarter based on engagement (opens and clicks)." * "Compare my recent newsletters against my promotional emails — which type gets more clicks?" * "Which of my campaigns had the highest unsubscribe rate? Let's try to figure out why." **Actions & Creation:** * `[ACTION]` "Draft an email campaign promoting a Black Friday sale for the next BFCM. Match the brand colors of MailerLite.com, offer 50% off Annual plans, and send it to all subscribers. Send a test email to [nikola@mailerlite.com](mailto:nikola@mailerlite.com) first." * `[ACTION]` "Find my best-performing newsletter from last month and resend it to everyone who didn't open it. Use the subject line: 'In case you missed it...'" * `[ACTION]` "Create an A/B test campaign for our new product launch. Test two subject lines: 'Introducing the Future of Gadgets' and 'Your New Favorite Gadget is Here'. Send it to 20% of my subscribers." * `[ACTION]` "Schedule my latest draft newsletter to be sent next Tuesday at 9:30 AM to my 'Active Subscribers' segment." *** #### **Automations** [#automations] Put your marketing on autopilot, from welcoming new subscribers to recovering lost sales. **Analytics & Insights:** * "For my welcome automation series, what's the completion rate, and which email in the sequence has the highest drop-off?" * "Show me a list of all my active automations along with their completion and conversion rates." * "Which of my automations is underperforming compared to the others?" **Actions & Creation:** * `[ACTION]` "Draft a new, better-performing version of the Welcome automation for all new subscribers. Make sure the emails follow MailerLite's tone of voice and visual look." * `[ACTION]` "Create an automation for abandoned carts. It should trigger when someone leaves a product in their cart for more than 3 hours. The first email should be a simple reminder. If they don't purchase in 24 hours, send a second email with a 10% discount code." * `[ACTION]` "In my 'Welcome Series', add a step that tags subscribers as 'Highly Engaged' if they click a link in any of the first three emails." *** #### **Subscribers & Segments** [#subscribers--segments] Understand, manage, and grow your audience with precision. **Analytics & Insights:** * "How many subscribers do I have, and what's the split between active, unsubscribed, and unconfirmed?" * "Can you provide a list of subscribers who have opened but not clicked on any of my last five newsletters?" * "Who are my most engaged subscribers based on recent activity? I want to send them a special thank you." * "How many subscribers are in each of my groups?" **Actions & Creation:** * `[ACTION]` "Create a segment named 'Opened but not clicked 90 days'. I'll fine-tune the exact filter rules in the dashboard afterwards." * `[ACTION]` "Create a new group called 'VIP Customers' and add everyone who has placed more than 5 orders in my shop." * `[ACTION]` "Add a custom field called 'Favorite Product' so I can personalize future campaigns." * `[ACTION]` "Show me all subscribers in the 'Inactive' segment so I can review them before cleaning up my list." *** #### **Forms & Landing Pages** [#forms--landing-pages] Optimize the very start of your customer's journey. **Analytics & Insights:** * "Compare the sign-up counts of my pop-up forms versus my embedded forms." * "Which of my forms has brought in the most subscribers?" **Actions & Creation:** * `[ACTION]` "Create a new embedded form for my blog's footer. It should only ask for an email address and have a button that says 'Join Our Community'." * `[ACTION]` "I'm hosting a webinar next month. Create a simple landing page form for it that collects a name and email address." *** #### **E-commerce** [#e-commerce] Sync and manage your store data so it can power campaigns, segments, and automations. **Analytics & Insights:** * "Which products generated the most revenue in my shop last month?" * "Show me customers who have placed more than 3 orders but haven't bought anything in the last 60 days." * "What's the average order value across my shop?" **Actions & Creation:** * `[ACTION]` "Import this list of products into my shop from the attached data." * `[ACTION]` "Create a 'Summer Sale' category and attach all of my seasonal products to it." * `[ACTION]` "Find customers who abandoned a cart in the last 24 hours and add them to my 'Cart Recovery' group." *** #### **Strategic Advice** [#strategic-advice] Get expert recommendations tailored to your specific account and performance. * "What are some recommended next steps to improve the open rate of my newsletters, given my current performance?" * "Based on my most popular newsletters, can you suggest three content ideas for my next campaign?" * "My engagement has slowed down. What are two strategies I could try to win back inactive subscribers?" * "How can I use personalization more effectively in my subject lines to increase open rates?" # MailerLite MCP Server (/mcp) This is the beta version of Model Context Protocol (MCP) server that provides seamless integration with MailerLite's email marketing API. This server enables AI assistants to manage subscribers, campaigns, groups, and many other things through standardized MCP tools. ## How MCP Works [#how-mcp-works] The Model Context Protocol (MCP) is a standardized protocol for AI assistants to interact with external systems. Think of it as USB-C port for AI. You can connect multiple MCPs that talk to each-other and get things done for you. ## Connecting a Client [#connecting-a-client] You can connect any MCP-compatible client to the running server. The server supports a streamable HTTP endpoint up to the latest MCP server specifications. Usually, you would just add `https://mcp.mailerlite.com/mcp` as a remote MCP address in any tooling that you are working with. ### Claude (desktop and web) [#claude-desktop-and-web] Open Claude (Desktop), go to Settings > Connectors, and then Add Custom Connector. Name can be whatever you want, but we suggest using MailerLite as name, and Remote MCP server URL is [https://mcp.mailerlite.com/mcp](https://mcp.mailerlite.com/mcp). Click connect and follow the login process. ### Claude Code [#claude-code] Execute this in terminal: ```bash claude mcp add --transport http mailerlite https://mcp.mailerlite.com/mcp ``` ### Gemini CLI [#gemini-cli] Add following lines in your `~/.gemini/settings.json` file: ```json { "mcpServers": { "mailerlite": { "httpUrl": "https://mcp.mailerlite.com/mcp", "timeout": 5000 } } } ``` ### VSCode [#vscode] You can use [one-click install](vscode:mcp/install?%7B%22name%22%3A%22mailerlite%22%2C%22gallery%22%3Afalse%2C%22url%22%3A%22https%3A%2F%2Fmcp.mailerlite.com%2Fmcp%22%7D) to add it to VSCode. ### Cursor [#cursor] [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=MailerLite\&config=eyJ1cmwiOiJodHRwczovL21jcC5tYWlsZXJsaXRlLmNvbS9tY3AifQ==) ### ChatGPT [#chatgpt] *Eligibility: Available in beta to Pro and Plus accounts on the web.* * First, Enable developer mode: Go to: Settings → Connectors → Advanced → Developer mode. * Go to back to Connectors main screen, click **Create** next to Browse connectors and in the dialog that opens enter the following: Name: MailerLite Description: leave empty or fill as you wish MCP Server URL: [https://mcp.mailerlite.com/mcp](https://mcp.mailerlite.com/mcp) Authentication: OAuth Click on **I trust this application** checkbox and then click Create. It will guide you through the authentication process. In order to use connectors in conversations: Open a new convo, choose Developer mode from the Plus menu and select connectors. You may need to explore different prompting techniques to call the correct tools. ## Available Tools [#available-tools] ### Subscriber Management [#subscriber-management] * **add\_subscriber**: Add a new subscriber or update an existing one (supports email, name, fields, groups) * **get\_subscriber**: Get subscriber info by ID or email * **update\_subscriber**: Update subscriber information (non-destructive) * **list\_subscribers**: List subscribers with filtering by status (active, unsubscribed, unconfirmed, bounced, junk) * **get\_subscriber\_activity**: Get activity history for a subscriber * **get\_subscriber\_count**: Get the total count of subscribers * **delete\_subscriber**: Delete a subscriber (keeps info for re-subscription) ### Campaign Management [#campaign-management] * **create\_campaign**: Create a new email campaign (regular, ab, resend types) * **get\_campaign**: Get specific campaign details * **list\_campaigns**: List campaigns with filtering by status and type * **update\_campaign**: Update campaign details (name, subject, from, content) * **delete\_campaign**: Delete a campaign * **schedule\_campaign**: Schedule a campaign to be sent * **cancel\_campaign**: Cancel a scheduled campaign * **get\_campaign\_subscribers**: Get subscribers who received a campaign, with filters * **get\_campaign\_links**: List the links in a sent campaign with their click stats * **get\_campaign\_link\_recipients**: Get the subscribers who clicked a specific link ### Group Management [#group-management] * **create\_group**: Create a new subscriber group * **update\_group**: Update a group name * **delete\_group**: Delete a group * **get\_group\_subscribers**: Get subscribers in a group * **assign\_subscriber\_to\_group**: Add a subscriber to a group * **unassign\_subscriber\_from\_group**: Remove a subscriber from a group * **import\_subscribers\_to\_group**: Bulk import subscribers into a group ### Segment Management [#segment-management] * **list\_segments**: List all segments * **create\_segment**: Create a new segment * **get\_segment**: Get a single segment's details * **update\_segment**: Update a segment name * **delete\_segment**: Delete a segment * **get\_segment\_subscribers**: Get subscribers in a segment, with status filtering ### Field Management [#field-management] * **list\_fields**: List custom subscriber fields * **create\_field**: Create a custom field (text, number, or date) * **update\_field**: Rename a custom field * **delete\_field**: Delete a custom field ### Form Management [#form-management] * **list\_forms**: List forms by type (popup, embedded, promotion) * **create\_form**: Create a new form * **get\_form**: Get a single form's details * **update\_form**: Update a form name * **delete\_form**: Delete a form * **get\_form\_subscribers**: Get subscribers who signed up through a form ### Automation Management [#automation-management] * **list\_automations**: List automations with filtering by name, group, and enabled status * **get\_automation\_activity**: Get subscriber activity for an automation, with status filtering * **create\_automation**: Create a draft automation * **build\_custom\_automation**: Plan and validate a custom automation before creating it * **start\_automation\_conversation**: Begin a guided, conversational automation build * **update\_automation\_email**: Update the content of an automation email step * **update\_automation\_delay**: Update the delay of an automation step * **dry\_run\_automation**: Validate an automation without sending anything * **send\_test\_automation**: Send test emails for an automation * **delete\_automation**: Delete an automation ### Templates [#templates] * **discover\_automation\_templates**: Browse available automation templates * **install\_template**: Install an automation template into the account * **list\_email\_templates**: List available email templates * **list\_form\_templates**: List available form templates ### Email Content [#email-content] * **generate\_email\_content**: Generate and validate HTML email content * **suggest\_subject\_lines**: Generate and validate subject line suggestions ### E-commerce Management [#e-commerce-management] * **manage\_ecommerce\_shops**: List, fetch, create, update, or delete shops * **manage\_ecommerce\_products**: List, fetch, create, update, delete, or bulk-import products in a shop * **manage\_ecommerce\_customers**: List, fetch, create, update, or delete customers in a shop * **manage\_ecommerce\_orders**: List, fetch, create, update, delete, or bulk-import orders in a shop * **manage\_ecommerce\_categories**: List, fetch, create, update, delete, or bulk-import product categories * **manage\_ecommerce\_carts**: List, fetch, or update shopping carts * **manage\_ecommerce\_cart\_items**: List, fetch, create, update, or delete the line items of a cart * **manage\_ecommerce\_category\_products**: List products in a category, or attach/detach a product Each `manage_ecommerce_*` tool takes an `action` parameter (e.g. `list`, `get`, `create`, `update`, `delete`, `import`) rather than exposing a separate tool per operation. ### Webhook Management [#webhook-management] * **list\_webhooks**: List all webhooks * **get\_webhook**: Get a specific webhook's details * **create\_webhook**: Create a new webhook with a name, URL, and events * **update\_webhook**: Update a webhook, including enabling/disabling it * **delete\_webhook**: Delete a webhook ### Discovery & Utility [#discovery--utility] * **search**: Search across MailerLite resources * **fetch**: Fetch a specific MailerLite resource by reference * **list\_resources**: List the resource types available to work with * **select\_resource**: Resolve a resource by name to its ID * **batch\_requests**: Run multiple API operations in a single batched request * **get\_dashboard\_link**: Get a deep link to edit a resource in the MailerLite dashboard ### Authentication [#authentication] * **get\_auth\_status**: Get the current authentication status ## Feedback [#feedback] We are always eager about feedback of the exciting things we are working on. If you have feedback about our MCP, feel free to send an email to [mcp@mailerlite.com](mailto:mcp@mailerlite.com).