NewZapp MCP server

An MCP server that lets Claude, ChatGPT and other MCP clients work with a NewZapp email marketing and internal communications account: the account and its licence, campaign reports, open heatmaps, contact groups, contact counts and a contact search that withholds personal data by default, and (when enabled) creating and updating contacts. It is built from NewZapp's public API documentation only: the OpenAPI 3.0.1 document "NewZapp API" v3 at https://my.newzapp.co.uk/swagger/v3/swagger.json, which is what the ReDoc page at https://my.newzapp.co.uk/api-docs renders.

Once it's connected, a comms team can ask things like:

• "How did last week's staff newsletter do: opens, clicks, unsubscribes?"

• "Which of our September campaigns had the best click-to-open rate?"

• "When do people actually open our emails? Show me the busiest hours."

• "How many contacts in the Managers group have unsubscribed or bounced?"

• "How many people opened the newsletter but didn't click?"

• With writes enabled: "Add our new starter Nia Jones to All staff, with Department set to Parks."

Tools

Array parameters are sent as repeated keys (TopicIds=7&TopicIds=99), as the GET /api/contacts description says. The Filter model is sent exactly as that description shows it: five parameters per filter, filters[i].condition, .field, .operator, .value and .order, with condition=null on the first filter.

Not covered on purpose: every DELETE endpoint (campaigns, contacts, groups, pages), POST /api/groups, POST /api/custom-fields, POST /abuse-complaint, GET /api/campaigns/{id}/html (the campaign's HTML), the landing page endpoints GET /api/pages and /api/pages/{id}, and GET /api/custom-fields (whose 200 has no schema; the custom field definitions come from GET /api/account, which has one). The API documents no endpoint that sends a campaign, and no tool here sends one.

Related MCP server: Amiqus MCP server

Setup

Requires Node 18 or later.

npm install
npm run build

Create an API key in NewZapp as the spec describes: click your profile image, go to Account Settings > API Integration and create a key. The server sends it as the X-Api-Key header. NewZapp's help centre says API integration "is not covered under general NewZapp support".

Claude Desktop: add this to claude_desktop_config.json:

{
  "mcpServers": {
    "newzapp": {
      "command": "node",
      "args": ["/absolute/path/to/newzapp-mcp/dist/index.js"],
      "env": { "NEWZAPP_API_KEY": "your-key" }
    }
  }
}

Claude Code:

claude mcp add newzapp -e NEWZAPP_API_KEY=your-key -- node /absolute/path/to/newzapp-mcp/dist/index.js

Safety defaults

• Read-only unless NEWZAPP_ALLOW_WRITES=true. Read tools carry the MCP readOnlyHint annotation. create_contact is marked non-destructive and non-idempotent; update_contact is marked destructive (it overwrites the fields you name) and idempotent. No tool deletes anything or sends a campaign.

• Contacts are people. By default search_contacts returns only each contact's ID, the unsubscribed, confirmed, suppressed and bounced flags, and the subscribe, unsubscribe, confirm and suppress-until dates. Email address, title, first and last name, company, job title, mobile and telephone numbers, date of birth and postal address are only returned with include_contact_details=true. A match on a search term or a Filter still confirms that such a contact exists, even when its details are withheld; the same holds for count_contacts, which returns a number only. create_contact does not echo the email address back (it returns the new ID and groups, and says so if NewZapp stored the address differently).

• In free text (campaign names, subjects and feedback, group, segment, topic and tag names, group descriptions, the account name and company, NewZapp's error messages) email addresses are replaced with [email redacted] and phone-number-like sequences with [phone redacted] by default, with an email pattern and a phone-number heuristic (international numbers with + or 00, bracketed UK area codes, and UK numbers starting with 0): international numbers written with + or 00, UK numbers with a bracketed area code, and UK-style 0… numbers of 9 to 11 digits with spaces, dots or hyphens. Other digit strings starting with 0 are redacted too, while numeric IDs and timestamps are left alone. include_contact_details=true returns the text as stored on the tools that have it (list_campaigns, get_campaign, get_campaign_summary, list_contact_groups, search_contacts); get_account always redacts.

• get_campaign and get_campaign_summary return records whose shape NewZapp does not document, and the summary is documented as "recipient action data", so per-recipient rows are the expected case. By default both go through an allowlist: numbers, true/false values and nulls are kept at any depth; text is kept only directly on the top-level record (with emails and phone numbers redacted as above); a list holding anything other than numbers, true/false values and nulls (per-recipient rows under any key name, but also the campaign's groups, topics, feedback and channel totals) is withheld whole; text nested deeper is withheld. On top of that, any key whose name suggests contact, identity or sender data is withheld whatever its value, a number included. Keys are matched in any spelling (emailAddress, email_address and emailaddress alike) on these words: mail, phone, mobile, fax, address, postcode, postal, birth, name, location, salary, wage, user agent, custom field, job title, sender, author, owner, created/modified/updated by, reply-to, and, as whole words, tel, zip, city, county, country, dob, ip and pay, plus keys named exactly from, to, cc, bcc, user or person. The campaign's own top-level name is the one exception. A key naming people (contacts, recipients, subscribers, people, person, members, users) is withheld when it holds a list or object. A mobile key is withheld when it holds a string or a number (a number there could be a phone number, so even a count by device is withheld), but kept when it holds an object such as the read-time breakdown by device. Everything withheld is listed by path under withheld_fields (at most 100 paths). Keys that suggest bank, card or payment data (bank, IBAN, sort code, card, card number, PAN, BIN, last4, CVV, payment, account number) or credentials (password, secret, token, API key, SMTP username) are never returned, not even with include_contact_details, and are listed under never_returned. include_contact_details=true returns the rest as stored. Strings longer than 1,000 characters are cut, and nesting deeper than 20 levels is replaced by a placeholder. The default output can still carry personal data in a top-level text field under an innocuous key (only emails and phone numbers are redacted there) or as a bare number under an innocuous key.

• Nothing is ever downloaded, and the campaign HTML endpoint is not used.

• Tool arguments are checked before any call is made. An unknown argument name is rejected rather than ignored, so a misnamed filter (email instead of search or filters, say) cannot silently turn a count or a search into one over the whole account. IDs: every path and ID parameter is an int32 in the spec, so IDs must be whole numbers from 1 to 2147483647. Dates must be real dates in YYYY-MM-DD or ISO 8601 date-time form (passed to NewZapp as given, although the spec types them as date-times; see Status). Parameters whose values the spec does not list (Status, OrderBy, group type, Device, Client, Condition, Filter operators) accept letters, digits, spaces, _, . and - only; Filter field names and the sort field accept letters, digits and _.

• Writes never change subscription status except in one direction: update_contact can mark a contact unsubscribed and cannot re-subscribe one, and create_contact sends no subscription flag. isUnsubscribed: false is never sent. Neither tool sends the documented deleted field, and suppressUntilDate is only ever sent back unchanged (next point).

• create_contact checks the account's custom fields (GET /api/account) and groups (GET /api/groups) when you pass their IDs, then looks for an existing contact with the same email (the Filter model with emailaddress and contains, compared exactly and case-insensitively on the results) and refuses to create a duplicate, pointing to update_contact.

• update_contact reads the contact first and sends back the full set of documented profile fields it has, its custom fields and its group IDs, with your changes applied. The spec does not say whether PUT /api/contacts/{id} replaces the whole contact or only the fields sent, so the body also carries isUnsubscribed: true when the contact is already unsubscribed and its current suppressUntilDate when it has one. Under either reading, then, the documented profile fields you did not name, the custom fields, the group memberships, an unsubscribe and a suppression date keep their current values (checked against the mock only; see Status). Group membership is only added to: the body carries the existing group IDs plus the new ones. A contact marked isDeleted is refused without a write.

• NewZapp documents no rate limit (neither the spec nor the "API Integration" help article mentions one). Requests are spaced 250 ms apart (about four per second). A 429 is retried at most twice for any method, including POST /api/contacts, on the assumption that a rate-limited request was not processed (see Status). The retry waits for Retry-After (whole or fractional seconds, or an HTTP-date; 2 s then 4 s when the header is absent or unreadable). A single wait is capped at 10 seconds: if NewZapp asks for a longer one the request gives up at once and the message says how long to wait. Because one tool call can make many requests (a listing pages up to 40 times, create_contact makes up to 7), each tool call also has one 40-second budget shared by all its requests, throttle and retry waits included, to stay under the MCP client's default 60-second request timeout: a retry wait that would end past the budget is not started, a request still running when it runs out is aborted, and a POST or PUT is not started with less than 10 seconds left (nothing is written). A listing that runs out of budget after at least one page returns the records it has, marked incomplete, with the skip to continue from.

• 502, 503 and 504 are retried the same way for GET only; when all three attempts fail the error says the service may be unavailable, without the gateway's HTML. A POST or PUT is never retried after a gateway error, because it may already have been processed; the error says to check with search_contacts before repeating it.

• Paging continues from the first record not returned, even when NewZapp sends a page longer than the Take asked for. A 200 whose body is not JSON (a proxy or login page in the way) is reported as an error naming NEWZAPP_BASE_URL, never as an empty list. An empty 200 body is accepted as success (the PUT documents no response body).

• A rejected key (401 or 403) produces a message that says which variable to fix, where the key is created, and to check that the API is enabled on the plan. Error text quoted from NewZapp, and the start of a non-JSON 200 body, is scrubbed of the configured API key and redacted like other free text. That redaction covers email addresses and phone numbers only: a name, date of birth or postcode in a NewZapp error message would be passed through.

Tests

npm test

The suite takes about 70 seconds (about 30 of them in the time-budget check, which waits out real Retry-After delays) and runs offline once spec.json is present (it is downloaded from my.newzapp.co.uk/swagger/v3/swagger.json on the first run when missing).

1. Checks the spec itself: OpenAPI 3.0.1, 22 operations, no servers block, no securitySchemes, the X-Api-Key instruction in info.description, every operation this server calls, the exact query parameter names of each (which the tools pass through), the documented Filter model encoding, that each used operation documents only a 200 response, which of them have no response schema (GET /api/campaigns/{id}, GET /api/campaigns/{id}/summary, PUT /api/contacts/{id}), that the spec carries no JSON examples, and that the mock's key (nz-test-key-not-real) is obviously fake and not in the spec. Then validates every fixture record with Ajv against the published component schemas (AccountDTO, CampaignReportDTO, CampaignHeatmapDTO, GroupViewModel, ContactDTO, ContactDetailsDTO), with negative controls showing that undeclared keys, ids above int32 and non-date-times are rejected. One adjustment is made for Ajv: CustomFieldDTO.value is {"nullable": true} without a type, which Ajv refuses; a schema without a type already accepts any value including null, so that nullable is dropped. Every other schema is used as published.

2. Starts a local mock of the API under /api that serves the fixtures with the X-Api-Key header, Skip/Take paging over bare JSON arrays, the documented filters it implements (Search, Status, TopicIds, FromDate/ToDate on campaigns; GroupId, Search, Unsubscribed, Bounced, Suppressed and the Filter model on emailaddress contains for contacts; type, searchValue, tagIds for groups; the rest are recorded but do not filter), 401 without the right key, 404 for unknown IDs, and a one-off 429 with Retry-After. The mock's list, record, count, contact-detail and create responses are validated against the documented response schemas. NewZapp documents no response schema and no example for the campaign detail or the campaign summary, so their shape is unconfirmed: the mock serves the campaign's CampaignReportDTO record as its detail (an assumption, checked against that schema once the invented keys are removed) with sender, author, reply-to, a scalar mobile, custom field, HTML and SMTP password keys invented to exercise the pass-through, and a summary whose shape is invented (aggregate counts, per-recipient rows under several key names with lower-case concatenated keys, a phone number stored as a number and addresses in free text, taken from a reviewer's probe that got past an earlier version) and not validated against anything. The status codes and bodies of errors are assumptions too (see Status).

3. Starts the built server and drives it over stdio with the official MCP client: 30 checks (33 in the whole suite) covering tools/list and every tool's annotations, unknown argument names rejected on every tool without a request, the 250 ms spacing between paging requests, every read tool, Skip/Take paging across three pages stopping at a short page and across three full pages stopping at an empty fourth, max_results with continuation by skip, a page longer than the Take asked for continued from the first record not returned, an API that ignores Skip detected instead of looped, heatmap cells outside the documented ranges ignored, a fractional count refused, every documented filter of list_campaigns, list_contact_groups, get_campaign_heatmap, get_campaign_summary, count_contacts and search_contacts passed through under its documented name (the Filter model as filters[i].* with condition=null first), redaction and withholding by default and their return on request (contacts, campaign subjects and feedback, group descriptions, the pass-through records under the allowlist with sender, author, contact and custom field keys and every list of records withheld, the per-recipient probe rows and contact keys in lower-case spellings withheld, a mobile object kept and a mobile string withheld, credentials never returned even on request, long HTML cut), create_contact not echoing the email, the SMTP username never returned, create_contact and update_contact request bodies validated against the documented request schemas (CreateOrUpdateContactApiDTO, CreateOrUpdateContactDTO) and asserted field by field, the duplicate and reference checks refusing without a write, an update to an unsubscribed and suppressed contact sending isUnsubscribed: true and the suppression date back, a contact marked isDeleted refused after one read, unsubscribe allowed and re-subscribe refused, the write gate with the variable unset and set to false, IDs, dates and parameter values refused before any call, the 404 message, the 401 message after exactly one request, the 403 message, the 429 retry waiting for Retry-After in the seconds, fractional-seconds and HTTP-date forms, the 2 s then 4 s fallback when the header is missing or unreadable, giving up at once on a wait above the cap and after three attempts on a persistent 429, a 429 on POST retried once, a 502 on a GET retried, a GET failing three times with 503 reported without the gateway HTML, a 502 on POST and a 504 on PUT never retried, a paged call slowed by a 429 before every page ending inside the 40-second budget with the records read so far and where to continue, a non-JSON 200 reported as an error (an email and phone number at the start of it redacted), an error body echoing the key and an email scrubbed of both, and that every request carried X-Api-Key and no Authorization header, used a documented method and path with documented parameter names only, and that every operation the server uses was exercised.

Two time-budget paths are not in the suite, because each needs a request held open for 30 to 40 seconds: aborting a request NewZapp never answers, and refusing to start a POST with less than 10 seconds of budget left. Both were checked once with a throwaway local server (no NewZapp host involved): get_account against a server that never answered returned the budget error after 40.0 s, and create_contact whose duplicate-check GET took 31 s returned "nothing was written" with no POST sent.

Status

This is a working prototype. It has not been run against the live API, because it was built without a NewZapp account (no self-serve trial was found). No request with credentials was made to NewZapp; the only requests to NewZapp's hosts were unauthenticated fetches of public pages: the spec, the API docs page, the help centre, and the pricing page (which refused the request). Everything below should be confirmed on a real account:

• The base URL https://my.newzapp.co.uk, inferred because the spec has no servers block.

• What a missing, wrong or unauthorised key gets back. The spec documents no error responses at all; the server treats 401 and 403 as a key problem, and the mock answers 401 with an empty body.

• The status codes and bodies of other errors: 404 for an unknown ID and the 400 shape are assumptions (the mock uses ASP.NET Core problem details, which the spec's text/json and application/*+json content types suggest). The server reads title, detail, message, error and errors from whatever comes back.

• The response shapes of GET /api/campaigns/{id} and GET /api/campaigns/{id}/summary (no schema, no example). The server does not depend on any field name there. The default output of those two tools is an allowlist (numbers, true/false values, top-level text, minus contact-looking keys), which may withhold more than needed on a real record; check what a real record contains, in particular whether the summary lists recipients and under what keys, and whether any top-level text or bare number identifies a person.

• Paging: the default and maximum Take, whether Skip/Take behave as offset and page size, and the end of a list. Nothing is documented: the server asks for 50 at a time and stops at an empty page or a page shorter than it asked for, so an API that silently caps Take below 50 would end a listing early. The default sort order of campaigns and contacts is not documented either.

• Parameter name casing. The server sends the names as the spec lists them (Search, Skip, GroupId, and lower-case from, to, id, groupId, type, searchValue, tagIds), while the example in the GET /api/contacts description writes them in lower case (?skip=0&take=10&field=emailAddress…). The Filter model is sent in the description's lower-case filters[i].* form.

• The Filter model: which field names and operators exist (the documentation shows only emailaddress, isconfirmed and contains, and says the full list is in the Contacts filter panel in NewZapp), whether the first filter's condition=null is needed as printed, and whether or works as a condition. What the separate Condition parameter does is not documented.

• The values of Status and OrderBy on campaigns, type on groups, and Device and Client on contacts; none is listed. The fixture values ("Sent", "Draft", "Internal", …) are invented.

• How Search matches (which fields, and whether several terms must all match), and what FromDate/ToDate, ModifiedFromDate/ModifiedToDate and the heatmap's from/to compare against, including time zones and whether the bounds are inclusive.

• Whether the date parameters (FromDate, ToDate, ModifiedFromDate, ModifiedToDate, the heatmap's from and to, SendDateTime) accept a bare YYYY-MM-DD. The spec types them as format: date-time; the server passes a date-only value through unchanged, which the tests only check on the wire.

• The date-time format in responses (the fixtures use Z-suffixed ISO 8601 because the schemas say date-time).

• CampaignReportDTO semantics: how selected, sent, bounced and failed relate, and whether NewZapp's own open and click rates are computed the way this server computes them (unique opens or clicks divided by sent).

• POST /api/contacts: whether the API itself rejects or merges a duplicate email, whether groupIds (or the separate groupId) is what adds a contact to groups, whether a custom field value can be sent as {id, value} without name and type, how dateOfBirth is stored (sent as YYYY-MM-DDT00:00:00Z), and whether creating a contact on an account with double opt-in switched on sends the person a confirmation email.

• PUT /api/contacts/{id}: whether it replaces the whole contact or only the fields sent, whether groupIds replaces or adds to the memberships, whether isUnsubscribed: true unsubscribes as expected, whether sending an existing suppressUntilDate back is accepted unchanged, and what the 200 body contains (the mock sends none).

• The duplicate check in create_contact relies on the Filter model with emailaddress contains; if that filter does not work as documented, the check could miss an existing contact.

• A 429 on POST /api/contacts is retried on the assumption that a rate-limited request was not processed; confirm NewZapp never creates the contact before answering 429.

• How many requests per second the API tolerates; nothing is documented, so the 250 ms spacing is a guess on the polite side. How long real requests take is unknown too: a long listing on a slow account can end early at the 40-second budget (it says where to continue).

Going to production

This version runs locally over stdio, with the account holder's own API key. For customers to connect from claude.ai or ChatGPT without handling keys, the next step is a remote server (Streamable HTTP) behind OAuth, hosted by NewZapp, a run of the suite against a real account to settle the points above, and then a listing in the Claude and ChatGPT connector directories.

Licence

MIT. Built by Alexandru Dragoș (alexandru.dragos96@gmail.com) with an AI agent (Claude) working under his direction.