Introduction

The Mailcamp API (version 1.0) is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Mailcamp API may differ as we release new versions over time. Log in to your Mailcamp dashboard to see the particular version, API base URI and authentication key.

Client libraries
cURL
 
sudo apt install curl

Authentication

Mailcamp API employs simple Token Authentication which is also referred to as query string parameter Authentication. That is, every Mailcamp user account has an authentication token. The token must be sent in the query string URL when making requests to protected resources:

https://mailcamp.io/api/v1?api_token=YOUR_API_TOKEN

Find your API Token

You will need to first login to your Mailcamp account to find the API TOKEN which is available in the API Docs dashboard

Lists

Mail Lists, also referred to as Audience, are at the center of email marketing management systems.
It is designed to help you collect and manage subscribed, non-subscribed, and unsubscribed contacts.
Mailcamp's List API allows you to create, edit your mail lists as well as manage your lists' contacts.

View Lists

Retrieve all your mail lists as well as every mail list's details like name, description, etc. You can also find every list's UID which is used as reference key for a particular list

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
VIEW LISTS
curl -X GET -H "accept:application/json" \
-G "https://app.mailcamp.io/api/v1/lists" \
-d "api_token={token_string}"
RESPONSE
[
    {
        "uid": "5fade5c93e42a",
        "name": "My Awesome Campaign",
        "from_email": "support@mailcamp.io",
        "from_name": "Customer Support",
        "status": null,
        "created_at": "2021-11-13 01:47:53",
        "updated_at": "2021-12-04 07:29:24"
    },
    {
        "uid": "5fc9e55410e10",
        "name": "List 1",
        ...
    },
    ...
]

Create List

A mail list is a collection of email addresses used by an individual or an organization to send marketing material to multiple recipients. You can have different lists of different group of contacts

Make a POST request to the /list resource along with your desired list details to create. On success, a unique List UID key is returned for the newly created list, which is used as a reference key for interacting with it.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
name string
List's name
from_email email
Default From email address
from_name string
Default From name
default_subject string
Default email subject
subscribe_confirmation string
Send subscription confirmation email (Double Opt-In)
send_welcome_email string
Send a final welcome email
unsubscribe_notification string
Send unsubscribe notification to subscribers
send_welcome_email string
Send a final welcome email
CREATE NEW LIST
curl -X POST 'https://app.mailcamp.io/api/v1/lists?api_token={token_string}' \
-H "Content-Type: application/json" \
-H "accept:application/json" \
-d '{
    "name": "List 1",
    "from_email": "abccorp@mailcamp.io",
    "from_name": "ABC Corp.",
    "default_subject": "Welcome to ABC Corp.",
    "subscribe_confirmation": "1",
    "send_welcome_email": "1",
    "unsubscribe_notification": "1"
}'
RESPONSE
{
    "status": 1,
    "message": "List was successfully created",
    "list_uid": "5fc9e55410e10"
}

Get List Details

Get detailed information of a List identified by a given UID passed to the API call.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
List's uid
GET LIST DETAILS
curl -X GET "https://app.mailcamp.io/api/v1/lists/65d181e30ecab?api_token={token_string}" \
-H "accept: application/json"
RESPONSE
{
    "list": {
        "uid": "5fc9e55410e10",
        "name": "List 1",
        "default_subject": "Welcome to ABC Corp.",
        "from_email": "admin@abccorp.org",
        "from_name": "ABC Corp.",
        "remind_message": null,
        "status": null,
        "created_at": "2024-02-18T04:04:51.000000Z",
        "updated_at": "2024-02-18T04:04:51.000000Z",
        "fields": [
            {
                "key": "EMAIL",
                "label": "Email",
                "type": "string",
                "tag": "EMAIL",
                "default_value": null,
                "visible": "1",
                "required": true,
                "custom_order": null
            },
            ..
        ]
    },
    "contact": null,
    "statistics": {
        "subscriber_count": 0,
        "open_uniq_rate": 0,
        "click_rate": 0,
        "subscribe_rate": 0,
        "unsubscribe_rate": 0,
        "unsubscribe_count": 0,
        "unconfirmed_count": 0
    }
}

Add Custom Field

Beside common fields of a contact like emails, names, addresses, cellphone numbers, etc. You can add customized fields to your mail lists to store more information about your list's contacts such as their preferences, scores, etc. and then you can organize contacts based on specific interest groups within your list/audience.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
type string
Choose one of these types: text, number, datetime.
label string
Field' label
tag string
The tag name may have alpha-numeric characters, as well as dashes and underscores.
default_value string
Default value of the field
ADD CUSTOM FIELDS
curl -X POST 'https://app.mailcamp.io/api/v1/lists/{uid}/add-field?api_token={token_string}' \
-H "Content-Type: application/json" \
-H "accept: application/json" \
-d '{
    "type": "text",
    "label": "Custom",
    "tag": "CUSTOM_FIELD_4",
    "default_value": "test"
}'
RESPONSE
{
    "status": 1,
    "message": "List's field was created",
    "field": {
        "type": "text",
        "label": "Custom",
        "tag":"CUSTOM_FIELD_1",
        "default_value":"test",
        "uid":"5fcae3cb6298f",
        "updated_at":"2020-12-05 01:35:07",
        "created_at":"2020-12-05 01:35:07"
    }
}

Delete List

Delete a list and completely erase the list's information in the web platform.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
List's uid
DELETE LIST
curl -X DELETE 'https://app.mailcamp.io/api/v1/lists/{uid}?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "status": 1,
    "message": "Deleted"
}

Subscribers

By definition, a subscriber is usually someone who is a member of one or more of your lists.
They may have subscribed themselves to your mail list via a subscription page or web form, or you may have imported their details from another source.
Subscribers are also referred to as Audience in Mailcamp email marketing web platform

List Subscribers

List all subscribers of a given list identified by a UID

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
List's uid
api_token string
Your API token. You can find it in your API main page when logged in.
open string
default: all; yes - opened some campaigns; no - not opened any campaign
click string
default: all; yes - clicked some campaigns; no - not clicked any campaign
per_page string
Number of subscribers per page. Default: 25
page string
Page number
VIEW SUBSCRIBERS
curl -X GET 'https://app.mailcamp.io/api/v1/subscribers?api_token={token_string}&list_uid={uid}&per_page=20&page=1' \
-H "accept: application/json"
RESPONSE
[
    {
        "uid": "5fd07b8b65284",
        "email": "nickyu88@gmail.com",
        "status": "subscribed",
        "FIRST_NAME": "Nick",
        "LAST_NAME": "KKu",
        "CUSTOM_FIELD_1": "test"
    },
    ...
]

Add Subscriber

Add a subscriber to a list identified by a UID. Once added, the subscriber's status would be either subscribed / active or pending depending on your list settings (single opt-in or double opt-in)

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
List's uid
EMAIL string
Subscriber's email
tag string
Subscriber's tags, seperated by a comma (,).
[OTHER_FIELDS...] string
All subscriber's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the list fields configuration)
ADD SUBSCRIBER
curl -X POST 'https://app.mailcamp.io/api/v1/subscribers?api_token={token_string}&list_uid={uid}' \
-H "Content-Type: application/json" \
-H "accept: application/json" \
-d '{
    "EMAIL": "test@gmail.com",
    "tag": "foo,bar,tag with space",
    "FIRST_NAME": "Marine",
    "LAST_NAME": "Joze"
}'
RESPONSE
{
    "status": 1,
    "message": "Confirmation email sent to the subscriber",
    "subscriber_uid": "5fd07ca421da0"
}

Get Subscriber's Details

Get detailed information of a subscriber identified by an UID code. Notice that a subscriber's UID is globally unique. A contact identified by his/her email address may have more than one UID if he or she is added to more than one list.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
GET SUBSCRIBER'S DETAILS
curl -X GET 'https://app.mailcamp.io/api/v1/subscribers/{subscriber_uid}?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "subscriber": {
        "uid":"5fd07b8b65284",
        "email":"anna122@gmail.com",
        "status":"subscribed",
        "source":null,
        "ip_address":null,
        "FIRST_NAME":"Ann",
        "LAST_NAME":"Anna",
        "CUSTOM_FIELD_1":"test"
    }
}

Update Subscriber Information

Update a subscriber's details, identified by subscriber UID. Notice that a subscriber's UID is globally unique. A contact identified by his/her email address may have more than one UID if he or she is added to more than one list.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Subsciber's uid
EMAIL string
Subscriber's email
tag string
Subscriber's tags, seperated by a comma (,).
[OTHER_FIELDS...] string
All subscriber's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the list fields configuration)
UPDATE SUBSCRIBER
curl -X PATCH 'https://app.mailcamp.io/api/v1/subscribers/{subscriber_uid}?api_token={token_string}' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
    "EMAIL": "test.edited@gmail.com",
    "tag": "foo,bar,tag with space",
    "FIRST_NAME": "Marine",
    "LAST_NAME": "Joze"
}'
RESPONSE
{
    "status": 1,
    "message": "Subscriber was successfully updated",
    "subscriber_uid": "5fd07b8b65284"
}

Find Subscribers by Email

In Mailcamp platform, a contact is identified by his/her unique email address and he or she may belong to more than one list with different list's specific values. For example, a contact may have different ADDRESS values in different lists

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
email email
Subsciber's email
FIND SUBSCRIBERS
curl -X GET 'https://app.mailcamp.io/api/v1/subscribers/email/{email_address}?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "subscribers": [
        {
            "uid":"5fd07b8b65284",
            "list_uid":"5fc9e55410e10",
            "email":"test22@gmail.com",
            "status":"subscribed",
            "source":null,
            "ip_address":null,
            "FIRST_NAME":"Marine",
            "LAST_NAME":"Joze",
            "CUSTOM_FIELD_1":null
        }
    ]
}

Add Tag

Add one or more tags to a given subscriber. Tagging allows you to add custom labels to your subscribers, giving you the ability to reach people based on specific traits.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Subscriber's uid
tag string
Subscriber's tags, seperated by a comma (,).
ADD SUBSCRIBER TAG
curl -X POST 'https://app.mailcamp.io/api/v1/subscribers/{uid}/add-tag?api_token={token_string}' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
    "tag": "foo,bar,tag with space"
}'
RESPONSE
{
    "status": 1,
    "message": "Tag was added successfully",
    "subscriber_uid": "5fd07ca421da0",
    "tags": ["foo","bar","tag with space"]
}

Subscribe

Add a subscriber to a list identified by a UID. Once added, the subscriber's status would be either pending. This also triggers a confirmation email sending to the subscriber's email address for verification.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
SUBSCRIBE
curl -X PATCH 'https://app.mailcamp.io/api/v1/lists/{list_uid}/subscribers/{uid}/subscribe?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "status": 1,
    "message": "Subscriber was subscribed"
}

Unsubscribe

Unsubscribe a contact from a given list. Notice that the contact is still available in the list but of unsubscribed status and Mailcamp will no longer send marketing emails to this contact. You can completely delete the contact from the list using the DELETE API method.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
list_uid string
Mail list's uid
uid string
Subsciber's uid
UNSUBSCRIBE
curl -X PATCH 'https://app.mailcamp.io/api/v1/lists/{list_uid}/subscribers/{uid}/unsubscribe?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "status": 1,
    "message": "Subscriber was unsubscribed"
}

Remove Subscriber

Remove a subscriber from a list and completely erase the subscriber's information in the web platform.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Subsciber's uid
DELETE SUBSCRIBER
curl -X DELETE 'https://app.mailcamp.io/api/v1/subscribers/{uid}?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "status": 1,
    "message": "Deleted"
}

Campaigns

An email marketing campaign is a coordinated set of individual email messages that are deployed across a specific period of time with one specific purpose. These specific purposes or calls-to-action (CTAs) can include the following: download a white paper, sign up for a webinar, or make a purchase. Mailcamp allows you to create a marketing campaign targeting one or more lists of your audience. You can also set up a campaign that targets a segment of a given list, rather than the entire list

IMPORTANT: as of version 1.0, Mailcamp API for campaigns is limited to READ ONLY methods. For setting up and running a campaign, users will need to login to the web UI.

List Campaigns

List all campaigns including new, running or closed ones.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
LIST CAMPAIGNS
curl -X GET 'https://app.mailcamp.io/api/v1/campaigns?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
[
    {
        "uid":"5fb48ff221b27",
        "name":"My Awesome Campaign",
        "type":"regular",
        "subject":"An Awesome Subject",
        "html":"<!DOCTYPE html>\n<html lang=\"en\">\n...",
            "plain": "One column layout...",
            "from_email": "marketing@Mailcamp.com",
            "from_name":"No Reply",
            "reply_to":"support@Mailcamp.com",
            "status":"new",
            "delivery_at":null,
            "created_at":"2021-11-18 03:07:30",
            "updated_at":"2021-11-18 03:07:41"
    },
    ...
]

Get Campaign's Details

Get detailed information and statistics of a campaign identified by a UID code.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Campaign's uid
GET CAMPAIGN DETAILS
curl -X GET 'https://app.mailcamp.io/api/v1/campaigns/{uid}?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "campaign": {
        "uid":"5fb48ff221b27",
        "name":"Untitled",
        "list":"",
        "segment":"",
        "default_subject":null,
        "from_email":"marketing@Mailcamp.com",
        "from_name":"Marketing Department",
        "remind_message":null,
        "status":"new",
        "created_at":[],
        "updated_at":[]
    },
    "statistics": {
        "subscriber_count":4,
        "uniq_open_rate":0,
        "delivered_rate":0,
        "open_count":0,
        "uniq_open_count":0,
        "last_open":"",
        "click_rate":0,
        "click_per_uniq_open":0,
        "click_count":0,
        "abuse_feedback_count":0,
        "last_click":"",
        "bounce_count":0,
        "unsubscribe_count":0,
        "links":[],
        "top_locations":[],
        "top_open_subscribers":[]
    }
}

Pause a Campaign

Pause a running campaign. You can later on run the campaign again to have it resume from where it left off.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
uid string
Campaign's uid
PAUSE CAMPAIGN
curl -X POST 'https://app.mailcamp.io/api/v1/campaigns/{uid}/pause?api_token={token_string}' \
-H "accept: application/json"
RESPONSE
{
    "status": "success",
    "message": "The campaign was paused",
    "campaign": {
        "uid": "6006510d1d421",
        "name": "Copy of Untitled",
        "list": "",
        "segment": "",
        ...
    }
}

Send Transactional API

Send email use Mailcamp's Transactional API.

If you want to receive notifications via callback, you can set it up on the dashboard page under the API - Webhook menu.

Things to note:

1. Before sending using the transactional API, ensure that the domain in the "from_email" has SPF or DKIM authentication. If it lacks either of these authentications, Mailcamp will reject the email sending and won't be able to forward it to the destination email.

2. Avoid titles and content containing spam to prevent the emails you send from ending up in the spam folder.

Parameters
api_token string
Your API token. You can find it in your API main page when logged in.
SENDING
curl -X POST \
    'https://app.mailcamp.io/api/v1/smtp?api_token={token_string}' \
    -H 'Content-Type: application/json' \
    -d '{
        "from_name": "Robert from Mailcamp",
        "from_email": "robert@doe.com",
        "to": "janne@doe.com",
        "subject": "Reschedule meeting",
        "message": "The meeting was rescheduled due to being busy on weekdays."
    }'
RESPONSE 200
{
    "message": "Sending. Thank you.",
    "id": "1707284327906192.65c3176713ca1@gmail.com"
}
RESPONSE 401
{"error":"Invalid API token"}
RESPONSE 401
{"error":"API token is missing"}