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": "<authToken>"
}

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.

Prefer to render the subject/content from a saved template instead of raw HTML? See Dynamic Templates.

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
}

Dynamic Templates

POST/crm/transactionEmail/add/submit

Bearer Token

This is the same endpoint as Submit Transactional Email — instead of supplying mailContent directly, you render it from a saved Dynamic Template by passing templateId.

The template's active version is rendered server-side against dynamicTemplateData (your merge-tag data) and used as the email's content. If you also supply mailSubject, your value overrides the template's own rendered subject; otherwise the template's rendered subject is used. A key missing from dynamicTemplateData simply renders as an empty string — it does not error.

The template must have an active version, or the request is rejected with This template has no active version yet. Activate a version before sending.

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.
`templateId`	Number	Yes	Id of the Dynamic Template to send. Its active version is rendered and used as the email's content.
`dynamicTemplateData`	Object	No	Merge-tag data the template's `{{ }}` tags resolve against.
`mailSubject`	String	No	Overrides the template's own rendered subject when supplied.
`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.

templateIdnumberrequired

Id of the Dynamic Template to send. Its active version is rendered and used as the email's content.

dynamicTemplateDataobjectoptional

The merge-tag data the template's {{ }} tags resolve against, e.g. {"first_name": "Alice", "order": {"number": "A-1024"}}.

mailSubjectstringoptional

Overrides the template's own rendered subject when supplied. Omit to use the template's subject.

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": "Acme Store",
  "fromId": "orders@yourdomain.com",
  "mailTo": ["alice@example.com"],
  "domain": "yourdomain.com",
  "templateId": 42,
  "dynamicTemplateData": {
    "first_name": "Alice",
    "is_vip": true,
    "order": { "number": "A-1024", "total": "$49.00" },
    "items": [
      { "name": "Wireless Mouse", "qty": 1 },
      { "name": "USB-C Cable", "qty": 2 }
    ]
  }
}'

Body

{
  "displayName": "Acme Store",
  "fromId": "orders@yourdomain.com",
  "mailTo": ["alice@example.com"],
  "domain": "yourdomain.com",
  "templateId": 42,
  "dynamicTemplateData": {
    "first_name": "Alice",
    "is_vip": true,
    "order": { "number": "A-1024", "total": "$49.00" },
    "items": [
      { "name": "Wireless Mouse", "qty": 1 },
      { "name": "USB-C Cable", "qty": 2 }
    ]
  }
}

{
  "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, segments, campaigns, templates, automations, reports 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.

Smithery

Mailzzy is also listed on Smithery, which can connect it to many MCP clients for you: Mailzzy on Smithery.

Available tools

Tools are grouped by domain and named mcp_crm_<domain>_<action>. Every tool works only on the account you signed in with.

Contact Management

mcp_crm_contacts_list: List contacts with filtering and pagination
mcp_crm_contacts_get: Get a single contact by ID
mcp_crm_contacts_create: Add a new contact to a group
mcp_crm_contacts_bulk_create: Add a small batch of contacts you've typed or pasted into the conversation
mcp_crm_contacts_upload_csv: Bulk-upload contacts from a CSV file
mcp_crm_contacts_update: Update fields on an existing contact
mcp_crm_contacts_delete: Archive a contact
mcp_crm_contacts_add_tag: Apply a tag to a contact
mcp_crm_contacts_remove_tag: Remove a tag from a contact
mcp_crm_contacts_remove_from_group: Remove a contact from a group
mcp_crm_contacts_export: Export the contacts in a segment, a group or the whole account as a downloadable CSV file
mcp_crm_contacts_export_status: Check an export's progress and get its download link (valid for 24 hours)

Group Management

mcp_crm_groups_list: List contact groups, each with its contact count
mcp_crm_groups_create: Create a new, empty contact group

Segment Management

mcp_crm_segments_list: List the segments in your account
mcp_crm_segments_get: Get a single segment and its filter
mcp_crm_segments_filter_options: Get the fields, operators and values available for building a segment
mcp_crm_segments_preview: Count how many contacts a segment filter would match, without saving it
mcp_crm_segments_create: Create a new segment
mcp_crm_segments_bulk_create: Create several segments in one call
mcp_crm_segments_update: Update an existing segment

Campaign Management

mcp_crm_campaigns_list: List campaigns with filtering by status
mcp_crm_campaigns_get: Get details for a single campaign
mcp_crm_audience_select: Choose a campaign's recipients and check they fit your account's email limits
mcp_crm_campaign_drafts_create: Create a campaign draft
mcp_crm_campaign_drafts_update: Update a campaign draft
mcp_crm_campaigns_send_test: Send a test of a campaign to a few of your own addresses
mcp_crm_campaigns_send: Send a campaign now or schedule it
mcp_crm_campaigns_cancel: Cancel a scheduled campaign that hasn't been sent yet

Template Management

mcp_crm_templates_list: List your saved and system email templates
mcp_crm_templates_get: Get a template's HTML and metadata
mcp_crm_templates_create: Create a new email template
mcp_crm_templates_update: Update an existing email template
mcp_crm_assets_image_import: Re-host an image from a public URL on your account's CDN for use in emails
mcp_crm_assets_image_upload: Upload an image to your account's CDN for use in emails

Automation Management

mcp_crm_automations_list: List the automations in your account
mcp_crm_automations_get: Get an automation and its steps
mcp_crm_automations_create: Create a new automation
mcp_crm_automations_update: Update an automation's settings
mcp_crm_automations_set_steps: Set an automation's trigger, conditions and actions

Senders & Domains

mcp_crm_senders_list: List the verified senders on your account
mcp_crm_senders_get: Get a single verified sender
mcp_crm_sending_domains_list: List the active sending domains a campaign can send through

Transactional Email

mcp_crm_txn_email_send: Send a transactional email to one recipient from a verified sender
mcp_crm_txn_email_list: List your transactional email send logs

Reports & Events

mcp_crm_reports_campaign_metrics: Sent, delivered, opened and clicked counts for one campaign
mcp_crm_reports_campaign_performance: Email performance across a date range
mcp_crm_reports_domain: Delivery, open, click, bounce and spam counts by recipient domain
mcp_crm_smtp_events_list: Delivery and engagement events: sends, deliveries, opens, bounces and failures

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

“Draft a campaign announcing our autumn sale, send me a test, then schedule it for Friday at 9 AM to my 'Newsletter' group.”

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

“Tag jane@acme.com as 'webinar-attendee'.”

ACTION

“Archive the contact spam@example.com.”

Segments

“List all of my segments.”

“Export the contacts in my 'Engaged last 30 days' segment as a CSV and give me the download link.”

“How many contacts opened an email in the last 30 days but never clicked?”

ACTION

“Create a segment of contacts in Canada who opened an email in the last 30 days.”

Templates & senders

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

“Which sender addresses are verified on my account?”

ACTION

“Create a template called 'Product Update' using our logo from acme.com/logo.png.”

Automations

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

ACTION

“Create a welcome automation that emails new contacts in my 'Newsletter' group a day after they join.”

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.