Getting Started

Mailzzy API

v1.0.0

This API provides secure endpoints for managing and validating API keys. Version 1.0.0 introduces key-based authentication features that allow clients to generate, activate/deactivate, and manage API access securely through standardized REST endpoints.

It serves as the foundation for authorized integrations, ensuring data security, controlled access, and seamless communication between client applications and Mailzzy backend services.

Base URL

All API requests are made to the following base URL. Every path in this reference is relative to it.

Base URL

https://api.mailzzy.com/

Authentication

Mailzzy uses a two-step token model.

Basic Auth — Call Obtain API Access with your Client ID and Client Secret (sent as an HTTP Basic Authorization header) to receive an authToken.
Bearer Token — Send that authToken as a Bearer token in the Authorization header of every subsequent secured request.

Your Client ID and Client Secret are available in the Mailzzy Dashboard under Client Credentials (an Admin role is required).

Authorization header

# Step 1 — obtain a token (Basic Auth)
Authorization: Basic <base64(clientId:clientSecret)>

# Step 2 — use the token on every other request
Authorization: Bearer <authToken>

Authentication

Obtain API Access

GET/core/public/api/access

Basic Auth

This endpoint lets your application securely authenticate using Basic Authentication and receive an authorization token (authToken) for protected API communication.

Basic authentication is a simple authentication scheme built into the HTTP protocol. To use it, send your HTTP requests with an Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.

This endpoint is typically called by trusted client systems (such as Mailzzy) to exchange valid client credentials for an access token. The returned authToken must be included in the Authorization header (as a Bearer token) for all subsequent secured API calls.

Note: Only the authToken should be used for authentication. The refreshToken field is under development and not currently required or supported.

How to Obtain Client Credentials To generate or find your Client ID and Client Secret, follow these steps:

Go to Mailzzy Dashboard: send.mailzzy.com/dashboard
Click the Menu in the top-right corner.
Select Client Credentials: Client Credentials settings
Copy your Client ID and Client Secret.

Ensure your account has an Admin role to access this section.

Headers

Authorizationstringrequired

Provided in the Basic Auth format using your Client ID and Client Secret.

e.g. Basic Q2xpZW50IElEOkNsaWVudCBTZWNyZXQ=

Appstringrequired

Identifies the application requesting access.

e.g. mailzzy

Responses

200

Successful response

406

Not Acceptable

Request

curl --request GET \
  --url https://api.mailzzy.com/core/public/api/access \
  --header 'Authorization: Basic <base64(clientId:clientSecret)>' \
  --header 'App: mailzzy'

{
  "email": "mailzzy.admin@company.com",
  "authToken": "eyJhbGciOiJIUzI1NiJ9.eyJzczpuIjoiRGhhcmEgTWFpbHp6eSBBZG1pbiIsImlzcyI6IlNPRlRTQUdFUyIsInNzOmlwIjp0cnVlLCJzczphcHAiOiJtYWlsenp5Iiwic3M6ciI6IjIiLCJzczp0IjpmYWxzZSwiYXVkIjoiU1NfQVVESUVOQ0UiLCJzczphIjoic2VuZCIsIm5iZiI6MTc2MTY1MjAzMiwiZXhwIjoxNzYxNjY2NDMyLCJzczppZCI6MjUzLCJpYXQiOjE3NjE2NTIwMzIsImp0aSI6IjVhMmRlYzFjLTg2NGItNDU3Yi05YzExLTI0ZmYwMmQ4MTJlOCIsInNzOmUiOiJkaGFyYS50aHVtbWFyK21hZG1pbkBzb2Z0c2FnZXMuY29tIiwic3M6cmZhIjp0cnVlfQ.RQyYVBAxkKHNsbLgFUYkLHfBAo5TwMUlxywU-U7Y123"
}

Contacts & Groups

Add Single Contact to Group

POST/crm/contact/add/group/{groupId}

Bearer Token

The Add Contact to Group endpoint allows an authenticated user to add a new contact to a specific group by providing detailed contact information such as name, email, phone number, and location details.

If you have not obtained API access yet, see Obtain API Access.

This API ensures data integrity through multiple validation checks before saving the contact. It prevents duplication, enforces data formatting standards, and validates that at least one of the primary identifiers — email or contact number — is provided.

If validation passes successfully, the contact is added to the specified group. In case of conflicts or invalid data, the API responds with descriptive error messages.

Validation Rules:

Either Email or Contact Number is mandatory.
Email must be valid and not blacklisted.
Phone Number must be valid, correctly formatted (E.164), and not blacklisted.
First Name is mandatory if enforced by campaign configuration.
Duplicate entries are not allowed — the same email or phone number cannot be linked to different records.

Path Parameters

groupIdstringrequired

Choose the group where you want to add this contact.

Headers

Authorizationstringrequired

JWT bearer token (the authToken returned by Obtain API Access).

e.g. Bearer <authToken>

Request Body · application/json

firstNamestringoptional

The contact’s first name.

lastNamestringoptional

The contact’s last name.

emailIdstringrequired

The contact’s email address used for communication.

timezonestringoptional

The contact’s timezone in GMT format, used for scheduling or localization.

addressstringoptional

The complete street address of the contact.

postalCodestringoptional

The contact’s postal or ZIP code.

citystringoptional

The city where the contact resides.

statestringoptional

The state or region associated with the contact’s address.

countrystringoptional

The country name of the contact.

contactNostringoptional

The contact’s phone number, including country code.

tagNamestringoptional

The tag or label assigned to categorize the contact (e.g., “usa_contact”).

Responses

200

Contact added

406

Not Acceptable

Request

curl --request POST \
  --url https://api.mailzzy.com/crm/contact/add/group/123 \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "Mailzzy",
  "lastName": "Mailzzy",
  "emailId": "mailzzy.admin@company.com",
  "timezone": "(GMT-04:00) America/New York",
  "address": "47 W 13th St, New York, NY 10011, USA",
  "postalCode": "12345",
  "city": "New York",
  "state": "NY",
  "country": "USA",
  "contactNo": "+1 (305) 555-5555",
  "tagName": "usa_contact"
}'

Body

{
  "firstName": "Mailzzy",
  "lastName": "Mailzzy",
  "emailId": "mailzzy.admin@company.com",
  "timezone": "(GMT-04:00) America/New York",
  "address": "47 W 13th St, New York, NY 10011, USA",
  "postalCode": "12345",
  "city": "New York",
  "state": "NY",
  "country": "USA",
  "contactNo": "+1 (305) 555-5555",
  "tagName": "usa_contact"
}

{
  "message": "Your new contact has been added successfully.",
  "code": 200
}

Contact Group Names Count

POST/crm/contact/fetch/all/contact-groups/count

Bearer Token

This endpoint returns the total number of contact groups available in the system.

If a search text is provided, the count is filtered based on matching group names.
If no search text is provided, the response returns the total count of all contact groups.

It is commonly used to support pagination workflows by determining the number of filtered records before retrieving full group details.

Headers

Authorizationstringrequired

JWT bearer token (the authToken returned by Obtain API Access).

e.g. Bearer <authToken>

Request Body · application/json

Field	Type	Required	Description
`searchText`	String	No	Text to search groups by name (empty string allowed).

searchTextstringoptional

Text to search groups by name (empty string allowed).

Responses

200

Type	Description
`Number`	Total number of groups matching the filters. No additional metadata is returned.

401

Unauthorized

Field	Type	Description
`timestamp`	String	Date-time when the error occurred (ISO format).
`status`	Number	HTTP status code — `401` for unauthorized request.
`error`	String	Short error description.
`message`	String	User-friendly message explaining the issue.
`path`	String	API endpoint that was accessed.

Request

curl --request POST \
  --url https://api.mailzzy.com/crm/contact/fetch/all/contact-groups/count \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
  "searchText": ""
}'

Body

{
  "searchText": ""
}

Contact Group Names

POST/crm/contact/fetch/all/contact-groups/page/{pageNo}/limit/{limit}

Bearer Token

This API retrieves a paginated list of contact groups.

Returns all contact groups when no search text is provided.
If a search text is provided, only groups matching the search text are returned.

It is used for displaying the list of groups in the “Group Management” or “Select Group” screen.

Cross-Verification Using Group Count API

Before calling this paginated endpoint, it is recommended to call the Group Count API to check whether any data exists for the applied filters.

Path Parameters

pageNointegerrequired

Page number (starts from 1).

limitintegerrequired

Number of records per page.

Headers

Authorizationstringrequired

JWT bearer token (the authToken returned by Obtain API Access).

e.g. Bearer <authToken>

Request Body · application/json

Field	Type	Required	Description
`searchText`	String	No	Search query for group names.

searchTextstringoptional

Search query for group names.

Responses

200

Field	Type	Description
`ID`	Number	Unique identifier of the contact group.
`NAME`	String	Human-readable name of the group.

401

Unauthorized

Field	Type	Description
`timestamp`	String	Date-time when the error occurred (ISO format).
`status`	Number	HTTP status code — `401` for unauthorized request.
`error`	String	Short error description.
`message`	String	User-friendly message explaining the issue.
`path`	String	API endpoint that was accessed.

Request

curl --request POST \
  --url https://api.mailzzy.com/crm/contact/fetch/all/contact-groups/page/1/limit/10 \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
  "searchText": "test"
}'

Body

{
  "searchText": "test"
}

[
  { "ID": 407, "NAME": "for sms 2" },
  { "ID": 402, "NAME": "kk sms test - 20th aug" }
]

Media Upload

POST/crm/secure/email/upload

Bearer Token

This API allows uploading email-related files in multiple supported document formats. It accepts a multipart/form-data request with validation applied on:

Allowed file extensions
Individual and total file size
Error handling for invalid files
All validations comply with backend logic.

File Validation Rules: Allowed File Extensions: doc, docx, txt, pdf, png, jpeg, jpg, gif, xlsx, xls, csv.

File Size Limits:

Constraint	Limit
Maximum size per individual file	10 MB
Maximum size for all files combined in one request	20 MB

Notes: Upload must contain files within allowed size and type limits. Unsupported formats or oversized uploads will be rejected. Do not include more than 20 MB of content in one request.

Headers

Authorizationstringrequired

JWT bearer token (the authToken returned by Obtain API Access).

e.g. Bearer <authToken>

Request Body · multipart/form-data

Field	Type	Required	Description
`file`	File	Yes	File to upload. Must meet extension and size constraints.

filefilerequired

File to upload. Must meet extension and size constraints.

Responses

200

Uploaded

401

Unauthorized

406

Not Acceptable

Request

curl --request POST \
  --url https://api.mailzzy.com/crm/secure/email/upload \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@/path/to/your-file.png'

{
  "message": "attachments/image.png",
  "code": 200
}

Submit Transactional Email

POST/crm/transactionEmail/add/submit

Bearer Token

This API is used to submit and send a transactional email through the Mailzzy platform. It allows you to define sender details, recipients, email subject, and HTML content.

Attachments are optional for transactional emails. If required, files must be uploaded before submitting the transactional email using the Media Upload API. Once uploaded, the returned attachment reference (file name) can be linked to the transactional email request. If no attachments are required, this step can be safely skipped.

Transactional Email Rate Limits:

Maximum Requests: You can send up to 100 transactional email requests per minute.
Request Timeout: Each request must be processed within 100 milliseconds.

Headers

Authorizationstringrequired

JWT bearer token (the authToken returned by Obtain API Access).

e.g. Bearer <authToken>

Request Body · application/json

Field	Type	Required	Description
`displayName`	String	Yes	Display name for the email request.
`mailSubject`	String	Yes	Subject line of the email.
`mailContent`	String (HTML)	Yes	HTML content of the email body.
`fromId`	String	Yes	Sender email address.
`mailTo`	Array<String>	Yes	List of recipient email addresses (currently only one is supported).
`domain`	String	Yes	Verified sending domain.
`attachmentFileNames`	Object	No	Attachment references returned by the Media Upload API.

displayNamestringrequired

Display name for the email request.

mailSubjectstringrequired

Subject line of the email.

mailContentstring (HTML)required

HTML content of the email body.

fromIdstringrequired

Sender email address.

mailToarray<string>required

List of recipient email addresses (currently only one is supported).

domainstringrequired

Verified sending domain.

attachmentFileNamesobjectoptional

Attachment references returned by the Media Upload API.

Responses

200

Accepted

401

Unauthorized

406

Not Acceptable

Request

curl --request POST \
  --url https://api.mailzzy.com/crm/transactionEmail/add/submit \
  --header 'Authorization: Bearer <authToken>' \
  --header 'Content-Type: application/json' \
  --data '{
  "displayName": "Mailzzy",
  "mailSubject": "Welcome User",
  "mailContent": "<html><head></head><body><p>Hello,</p><p>This is my first transactional email request, sent from Mailzzy.</p></body></html>",
  "attachmentFileNames": {
    "fileName": "attachments/fileName"
  },
  "fromId": "sender email id",
  "mailTo": ["user email id"],
  "domain": "your_domain"
}'

Body

{
  "displayName": "Mailzzy",
  "mailSubject": "Welcome User",
  "mailContent": "<html><head></head><body><p>Hello,</p><p>This is my first transactional email request, sent from Mailzzy.</p></body></html>",
  "attachmentFileNames": {
    "fileName": "attachments/fileName"
  },
  "fromId": "sender email id",
  "mailTo": ["user email id"],
  "domain": "your_domain"
}

{
  "message": "Your request is received.",
  "code": 200
}

MCP Server

Mailzzy MCP Server

Connect AI assistants like Claude, Gemini, Cursor, and VS Code to Mailzzy over the Model Context Protocol.

This is the beta Model Context Protocol (MCP) server that provides a seamless integration with Mailzzy’s email-marketing API. It lets AI assistants manage contacts, groups, campaigns, templates, and transactional email through standardized MCP tools — scoped to your own account.

How MCP works

The Model Context Protocol is a standardized way for AI assistants to interact with external systems — think of it as a USB-C port for AI. You connect the Mailzzy MCP server to any MCP-compatible client, and the assistant can call Mailzzy tools on your behalf. Every tool runs inside your authenticated account, so an assistant can never reach another tenant’s data.

Connecting a client

You can connect any MCP-compatible client to the server. It exposes a streamable HTTP endpoint — add this remote MCP address in whatever tooling you are working with:

MCP endpoint

https://api.mailzzy.com/crm/mcp/

The server is an OAuth 2.1 resource server. End-user clients such as Claude Desktop and Claude.ai authenticate with OAuth 2.1 + PKCE — on first connect you are prompted to sign in and authorize access to your Mailzzy account. No API key is pasted into the client.

Claude (desktop and web)

Open Claude, go to Settings → Connectors, then Add custom connector. Name it Mailzzy and use the remote MCP server URL above, then connect and complete the sign-in.

Claude Code

Add the server from your terminal:

Terminal

claude mcp add --transport http mailzzy https://api.mailzzy.com/crm/mcp/

Gemini CLI

Add the following lines in your ~/.gemini/settings.json file:

settings.json

{
  "mcpServers": {
    "mailzzy": {
      "httpUrl": "https://api.mailzzy.com/crm/mcp/",
      "timeout": 5000
    }
  }
}

Cursor & VS Code

Add Mailzzy as an HTTP MCP server in your editor’s MCP configuration:

mcp.json

{
  "mcpServers": {
    "mailzzy": {
      "type": "http",
      "url": "https://api.mailzzy.com/crm/mcp/"
    }
  }
}

ChatGPT

In ChatGPT, open Settings → Connectors (with developer mode enabled), choose Add custom connector, and enter the MCP server URL above. Authorize access to your Mailzzy account when prompted. Available on plans where MCP connectors are enabled.

Available tools

Tools are grouped by domain and named <domain>.<verb>. Destructive actions — deleting a contact or sending a campaign — are split into a preview tool that reports exactly what will change and a commit tool that carries it out, so nothing irreversible happens in a single step.

Contact Management

contacts.list: List contacts with filtering and pagination
contacts.get: Get a single contact by ID or email
contacts.create: Add a new contact to a group
contacts.update: Update fields on an existing contact (non-destructive)
contacts.delete.preview: Preview which contact will be removed before deleting
contacts.delete.commit: Permanently delete a contact after a preview

Group Management

groups.list: List contact groups, optionally filtered by name
groups.count: Count contact groups matching a search
groups.add_contact: Add an existing contact to a group

Campaign Management

campaigns.list: List campaigns with filtering by status
campaigns.get: Get details for a single campaign
campaigns.send.preview: Preview a campaign send — recipients and content
campaigns.send.commit: Send a campaign to its recipients after a preview
campaigns.cancel: Cancel a scheduled campaign send
campaigns.reports: Opens, clicks, bounces, and unsubscribes for a campaign

Segment Management

segments.list: List segments in your account
segments.delete: Delete a segment you no longer need

Template Management

templates.list: List your saved email templates
templates.get: Get a template's HTML and metadata

Sender Management

senders.list: List the verified sender identities on your account

Automation Management

automations.list: List the automations configured in your account

Transactional Email

email.send: Send a transactional email from a verified sender
media.upload: Upload an attachment to reference in a transactional email

Deliverability & Events

smtp.events: Query delivery and engagement events — deliveries, opens, clicks, bounces, unsubscribes

Authentication

OAuth 2.1 + PKCE: End-user clients such as Claude sign in and authorize access
Service-account tokens: Internal agents authenticate with a bearer token; tools never accept an account ID

MCP Server

Examples

Example prompts that show how AI assistants can manage campaigns, contacts, segments, and transactional email through the Mailzzy MCP server. 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; the rest are read-only questions.

Campaigns & reports

Your assistant can be your data analyst and scheduler in one.

“List my campaigns and tell me which ones are still drafts.”

“Show the open, click, and bounce rates for my most recent campaign.”

“Which of my campaigns had the highest unsubscribe rate — let's figure out why.”

ACTION

“Send my 'August Newsletter' campaign — preview the recipients first, then commit.”

ACTION

“Cancel the scheduled send for my 'Flash Sale' campaign.”

Contacts & groups

“How many contacts are in my 'Newsletter' group?”

“Look up the contact jane@acme.com and show their details.”

ACTION

“Add a new contact jane@acme.com named Jane to the 'VIP' group.”

ACTION

“Update the phone number for john@acme.com to +1 305 555 5555.”

ACTION

“Delete spam@example.com — show what will be removed before committing.”

Segments

“List all of my segments.”

ACTION

“Delete the 'Old leads' segment.”

Templates & senders

“List my email templates and show me the HTML for 'Welcome'.”

“Which sender addresses are verified on my account?”

Automations

“What automations do I have configured, and which ones are active?”

Transactional email

ACTION

“Send a transactional welcome email to jane@acme.com from my verified sender.”

Deliverability & events

“Show the delivery events for my last campaign — were there any bounces?”

“Did jane@acme.com open or click my latest email?”

Feedback

The MCP server is in beta and evolving quickly. If something is missing or behaves unexpectedly, let us know.