K2MailerDevelopers and administrators

K2Mailer REST API Complete Guide: Build APIs Developers Love

Learn what a REST API is, how endpoints and HTTP methods work, and how to build, test & secure RESTful APIs with K2Mailer’s simple beginner-friendly guide.

Last updated:

In the app→Settings → API

Quick answer: what is a REST API and how do you use it with K2Mailer?

A REST API is a web interface that lets one program work with another over HTTP, using standard methods such as GET, POST, PATCH, and DELETE on URLs called endpoints. K2Mailer’s REST API lets your own code manage lists, contacts, custom fields, groups, and saved broadcast content. You create a scoped API key in Settings → API, send it as a Bearer token, and call endpoints under https://app.k2mailer.com/api/v1.

Responses come back as JSON. The API enforces the same consent and suppression rules as the app, so an API call cannot quietly resubscribe someone who has opted out.

  • Base URL: https://app.k2mailer.com/api/v1.
  • Authentication: Authorization: Bearer YOUR_API_KEY, using a key created in Settings → API.
  • Format: JSON requests and responses.
  • Rate limit: 60 requests per minute.
  • Access control: least-privilege scopes such as lists.read and contacts.write.

What is a REST API? Meaning and definition

REST stands for Representational State Transfer, an architectural style described by Roy Fielding in 2000. A REST API, also called a RESTful API, exposes resources such as a contact or a list at predictable URLs and lets clients act on them with standard HTTP methods. You can read the background in Wikipedia’s REST overview and the method definitions in the MDN HTTP methods reference.

The idea is simple. Each request carries everything the server needs, the server does not keep client state between calls, and the response describes the resource, usually as JSON. That makes REST easy to test with a browser, curl, or any programming language.

REST API vs API: what is the difference?

API is the broad term for any way software talks to other software, including code libraries, operating system calls, and web services. A REST API is one specific kind of web API. When people search for api and rest api together, they usually want to know where REST fits among other styles such as GraphQL, SOAP, or webhooks.

Choose REST when you want predictable URLs, cached reads, and tooling that works everywhere. Choose webhooks when you want to be told about events instead of asking. Many products offer both, and K2Mailer’s MCP agent connection covers the case where an AI assistant, not your own code, needs safe access.

How a REST API works: endpoints, methods, and responses

Endpoint
A URL that represents a resource, such as /lists or /contacts. The base URL plus the path forms the full request URL.
GET
Reads a resource or a collection without changing it.
POST
Creates a resource or runs an action, such as creating a contact.
PATCH
Updates part of an existing resource, such as one contact field.
DELETE
Removes a resource.
Headers
Metadata sent with a request, including the Authorization header that carries your Bearer key.
Status code
The HTTP result: 200 for success, 401 for a bad key, 403 for a missing scope, 422 for validation errors, and 429 when rate limited.
JSON body
The structured data you send or receive. K2Mailer wraps most responses in a status and response envelope.

REST API example: a K2Mailer request and response

A simple REST API example makes the pattern clear. This request lists your lists using the base URL and a Bearer key. Replace YOUR_API_KEY with a key that has the lists.read scope.

curl --request GET \
  --url 'https://app.k2mailer.com/api/v1/lists' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'

Check the status field as well as the HTTP code

Some business-rule failures can return HTTP 200 with status set to Error. Inspect both the HTTP code and the JSON status before you treat a call as successful.

How to create a REST API key in K2Mailer

  1. 1

    Open Settings → API and enable API access for the tenant.

  2. 2

    Select Create API Key, give the integration a clear name, and grant only the scopes it needs.

  3. 3

    Choose an expiry period or Never, then create the key.

  4. 4

    Copy the full secret from the one-time confirmation. K2Mailer does not display newly created secrets again.

  5. 5

    Send the secret in the Authorization header as Bearer YOUR_API_KEY.

  6. 6

    Use the complete endpoint reference at k2mailer.com/help/api for endpoint fields, response examples, scopes, pagination, and rate limits.

How to create a REST API of your own: five design rules

Many readers search for how to create REST API projects as builders, not only as consumers. The same rules that make the K2Mailer API pleasant to use apply to any API you design. Model resources as nouns, such as /contacts, and let the HTTP method carry the verb. Return consistent JSON, use accurate status codes, and version the base path, as K2Mailer does with /api/v1.

Add authentication and least-privilege scopes from day one, document every field with an example, and set a rate limit so one client cannot overwhelm the service. Test with curl or a client such as Postman before you publish, and treat your documentation as part of the product.

  • Resources as nouns, methods as verbs.
  • Consistent JSON and accurate status codes.
  • Versioned base path.
  • Authentication, scopes, and rate limits.
  • Documentation with copy-ready examples.

Available scopes and current boundaries

  • account.read reads basic tenant account information.
  • clients.write creates client workspaces through approved provisioning workflows.
  • groups.read and groups.write control group access.
  • lists.read and lists.write control list access.
  • custom_fields.read and custom_fields.write control contact custom fields.
  • contacts.read and contacts.write control canonical contact and membership operations supported by the API.
  • campaigns.read and campaigns.write control saved broadcast content. These endpoints do not send or schedule a campaign.

Canonical contact API behavior

Current contact operations validate tenant-owned list IDs and can attach a canonical contact to zero, one, or many lists. Attaching an existing email reuses the contact identity rather than creating another person row.

An API call does not silently reopen an unsubscribed membership. When renewed consent is valid, the caller must explicitly request resubscription using the supported allow_resubscribe behavior. A DOI list returns to Pending DOI and still requires valid confirmation.

Global marketing opt-out, complaint, hard-bounce, and applicable suppression protections remain more restrictive than an API-requested list membership state. See manage contacts and import contacts for the matching app behavior.

Manage keys safely

  • Create a separate key for each integration such as Production, reporting, or an internal service.
  • Use least-privilege scopes. Read endpoints and write endpoints require the corresponding scopes.
  • Review Last used and the last-used IP to identify stale or unexpected integrations.
  • Revoke a compromised or retired key individually. Revoking one key does not affect other active keys.
  • Expired and revoked keys return 401. A valid key without the required endpoint scope returns 403.
  • Disabling tenant API access blocks every API key for that tenant.

The secret is shown once

Store API keys in server-side secret management. Never place them in browser JavaScript, a mobile bundle, a public repository, logs, or support screenshots.

Responses, rate limits, and pagination

  • Most resource responses use a status and response JSON envelope. GET /user returns the user object directly.
  • Some business-rule failures can use HTTP 200 with status set to Error, so inspect both the HTTP code and JSON status.
  • Invalid, expired, or revoked keys use HTTP 401. Missing scope or disabled tenant API access uses HTTP 403. Validation uses 422 and rate limiting uses 429.
  • K2Mailer REST routes are limited to 60 requests per minute by the application API middleware.
  • Collection endpoints use start_from as a zero-based offset and return up to 500 records. They do not accept a limit parameter.

REST API uses and benefits for email marketing

Typical REST API uses in email marketing include syncing new signups from a website or CRM into a list, updating custom field values when a customer changes plan, reading list data for reports, and storing campaign content created by another tool. Because the API reuses canonical contacts, you avoid duplicate records when the same person joins several lists.

The main REST API benefits are simplicity, language independence, and predictable behavior. Any language with an HTTP client can call it, caching and retries are straightforward, and scoped keys limit the damage if a secret leaks. Pair it with custom fields to carry business data into personalization and segments.

  • Sync website, CRM, or checkout signups into K2Mailer lists.
  • Keep custom fields current from your product database.
  • Read list and contact data for dashboards and audits.
  • Create saved broadcast content from your own tools.

WordPress REST API and Shopify REST API: how they relate

Searchers often meet K2Mailer’s API after working with a store or site platform. The WordPress REST API exposes posts, users, and custom data as JSON, which makes it a common source of signups to send into K2Mailer. Shopify’s REST Admin API exposes customers and orders, although Shopify now steers new apps toward GraphQL.

In both cases the pattern is the same. Your integration reads a new customer or subscriber from the platform, then calls the K2Mailer contacts endpoint with the email, names, list IDs, and any custom field values. Always collect marketing consent first, and let K2Mailer’s protections handle opted-out addresses.

Legacy API keys

Existing tokens created before multi-key management are migrated as Legacy API Key credentials with full access for compatibility.

Create a new scoped key for each integration, update the integration to use it, verify traffic in Last used, and then revoke the legacy key.

REST API terms explained

REST API meaning
A web API that follows REST principles: resources at URLs, standard HTTP methods, and stateless requests.
Rest API stands for
Representational State Transfer.
K2Mailer rest API
The API at https://app.k2mailer.com/api/v1 for lists, groups, contacts, custom fields, and saved broadcast content.
What is REST API authentication
Proof of identity on each request. K2Mailer uses a Bearer API key with scopes.
API scope
A permission attached to a key, such as contacts.read or lists.write.
Rate limit
The maximum request volume allowed per minute, which is 60 for the K2Mailer REST routes.
Pagination
Reading a large collection in pieces. K2Mailer uses start_from as an offset and returns up to 500 records.

Frequently asked questions

What does REST API stand for?
REST stands for Representational State Transfer. A REST API follows that style by exposing resources at URLs and using standard HTTP methods such as GET, POST, PATCH, and DELETE.
What is the difference between an API and a REST API?
An API is any interface that lets software talk to software. A REST API is a specific web API style that uses resource URLs, HTTP methods, and stateless requests, usually returning JSON.
How do I create a K2Mailer API key?
Open Settings → API, enable API access, select Create API Key, choose scopes and an expiry, then copy the secret from the one-time confirmation and send it as a Bearer token.
Is the K2Mailer REST API rate limited?
Yes. K2Mailer REST routes are limited to 60 requests per minute. Exceeding it returns HTTP 429, so queue or batch your calls.
Can the API send or schedule a campaign?
No. The campaigns scopes control saved broadcast content only. The endpoints do not send or schedule a campaign.
Is a REST API free to use?
REST itself is an open style with no license fee, and tools such as curl are free. Whether API access is included depends on your K2Mailer plan, so check the pricing page or start a free trial.
Do I need an API key for the MCP connection?
No. The MCP connection uses standard OAuth 2.0 sign-in. API keys are only used for the REST API.

Developer reference

Open the complete API reference

Review authentication, parameters, rate limits, cURL requests, and example responses.

Browse endpoints

Keep learning: related guides in this topic

Was this guide enough?

Contact support if your screen or result is different.

Contact support