Mailtarget Open API

Complete API reference for the Mailtarget email platform. 401 endpoints across email sending, contact management, analytics, security, and compliance.

Authentication — All endpoints require a Bearer token:
Authorization: Bearer MAILTARGET_API_KEY

Base URL — https://api.mailtarget.co

Response Format — Success: {"data": {...}, "meta": {...}} · Error: {"message": "...", "error": "ERROR_CODE"}

Campaigns

5 endpoints

Create, manage, and send email campaigns to your contact lists. Supports scheduling, personalization with merge tags, and campaign lifecycle management.

POST /v?/campaigns
cURL Example 
curl -X POST https://apiconfig.mailtarget.co/v?/campaigns \
  -H "Authorization: Bearer MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome Email",
    "type": "ONE_TIME",
    "startType": "FIX_TIME",
    "dueDate": "2026-04-15T10:00:00Z",
    "sender": {"name": "Mailtarget", "email": "noreply@mailtarget.co"},
    "recipients": {"labels": ["new-users"]},
    "htmlContent": "<html><body><h1>Welcome</h1></body></html>",
    "emailType": "HTMLV3",
    "snippet": "Welcome to our platform"
  }'
GET /v?/campaigns
cURL Example 
curl -X GET "https://apiconfig.mailtarget.co/v?/campaigns?page=1&perPage=20&search=welcome" \
  -H "Authorization: Bearer MAILTARGET_API_KEY"
GET /v?/campaigns/:id
cURL Example 
curl -X GET https://apiconfig.mailtarget.co/v?/campaigns/663f1a2b4c5d6e7f8a9b0c1d \
  -H "Authorization: Bearer MAILTARGET_API_KEY"
PUT /v?/campaigns/:id
cURL Example 
curl -X PUT https://apiconfig.mailtarget.co/v?/campaigns/663f1a2b4c5d6e7f8a9b0c1d \
  -H "Authorization: Bearer MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Updated Welcome Email", "snippet": "Updated"}'
DELETE /v?/campaigns/:id

curl -X DELETE https://apiconfig.mailtarget.co/v?/campaigns/663f1a2b4c5d6e7f8a9b0c1d \

cURL Example 
curl -X DELETE https://apiconfig.mailtarget.co/v?/campaigns/663f1a2b4c5d6e7f8a9b0c1d \
  -H "Authorization: Bearer MAILTARGET_API_KEY"

A/B Testing

2 endpoints

Test different subject lines, content, or send times to find what performs best before sending to your full list.

POST /v?/campaigns/:id/ab-test
GET /v?/campaigns/:id/ab-test/results

Automation

6 endpoints

Build automated email sequences triggered by events (signup, purchase, date-based). Set up drip campaigns and behavioral workflows.

POST /v?/automations
GET /v?/automations
GET /v?/automations/:id
PUT /v?/automations/:id
DELETE /v?/automations/:id
POST /v?/automations/:id/activate

Campaign Actions

3 endpoints

Perform actions on campaigns: send, pause, resume, cancel, duplicate, or schedule for later delivery.

POST /v?/campaigns/:id/send

Trigger immediate send untuk campaign yang sudah lengkap dan masih berada di stage yang bisa dikirim.

Request Body
{
  "data": {
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
    "stage": "SENDING",
    "message": "Campaign is being sent"
  }
}
Response (200)
{
  "data": {
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
    "stage": "SENDING",
    "message": "Campaign is being sent"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/campaigns/663f1a2b4c5d6e7f8a9b0c1d/send' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/campaigns/:id/schedule

Menjadwalkan campaign untuk dikirim di waktu tertentu.

Request Body
{
  "dueDate": "2026-04-15T10:00:00Z"
}
Response (200)
{
  "data": {
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
    "stage": "SCHEDULED",
    "dueDate": "2026-04-15T10:00:00Z",
    "message": "Campaign scheduled"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/campaigns/663f1a2b4c5d6e7f8a9b0c1d/schedule' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "dueDate": "2026-04-15T10:00:00Z"
  }'
POST /v?/campaigns/:id/cancel

Membatalkan campaign yang sudah dijadwalkan dan mengembalikannya ke stage draft.

Request Body
{
  "data": {
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
    "stage": "DRAFT",
    "message": "Campaign cancelled"
  }
}
Response (200)
{
  "data": {
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
    "stage": "DRAFT",
    "message": "Campaign cancelled"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/campaigns/663f1a2b4c5d6e7f8a9b0c1d/cancel' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Forms

3 endpoints

Create and manage subscription forms that can be embedded on your website to collect new contacts.

GET /v?/forms
GET /v?/forms/:id
GET /v?/forms/:id/submissions

Vouchers

3 endpoints

Generate and manage promotional voucher codes that can be distributed via email campaigns.

POST /v?/vouchers
GET /v?/vouchers
DELETE /v?/vouchers/:id

Batch Sending

5 endpoints

Send personalized emails to large lists in a single API call. Supports per-recipient substitution data and scheduling.

POST /v?/batches

{ "name": "Welcome batch", "messages": [{ "to": [{"email": "a@b.com"}], "from": {"email": "noreply@mailtarget.co", "name": "MT"}, "subject": "Welcome", "bodyHtml": "<h1>Hi</h1>" }] }

GET /v?/batches

— GET /v?/batches/:id

POST /v?/batches/:id/send

Trigger. Response: `{ "data": { "status": "sending" } }`

DELETE /v?/batches/:id

Cancel pending batch. Error 400 if already sending/completed.

Categories

3 endpoints

Organize campaigns and single sends into categories for filtering and reporting.

GET /v?/categories

{ "data": [{ "name": "transactional", "description": "", "messageCount": 15000, "lastUsedAt": "2026-04-10T08:00:00Z" }] }

GET /v?/categories/:name/stats

Stats for a category. Query: `dateFrom`, `dateTo`.

DELETE /v?/categories/:name

Response: `{ "message": "Category removed" }`

Scheduled Messages

4 endpoints

View and manage emails that are queued for future delivery. Cancel or reschedule pending sends.

GET /v?/scheduled-messages

Query: `page`, `perPage`, `dateFrom`, `dateTo`.

GET /v?/scheduled-messages/:id

Full message detail.

PUT /v?/scheduled-messages/:id

Update schedule time. `{ "scheduledFor": "2026-04-16T10:00:00Z" }` Must be future.

DELETE /v?/scheduled-messages/:id

Cancel. Response: `{ "message": "Scheduled message cancelled" }`

Message Streams

6 endpoints

Separate your sending into isolated streams (transactional, marketing, inbound) with independent reputation and settings.

POST /v?/message-streams

Membuat message stream baru. Default type `transactional` jika tidak diisi.

Request Body
{
  "name": "Transactional Emails",
  "type": "transactional",
  "description": "Order confirmations and receipts"
}
Response (201)
{
  "data": {
    "_id": "ms_001",
    "name": "Transactional Emails",
    "type": "transactional",
    "description": "Order confirmations and receipts",
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/message-streams' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Transactional Emails",
    "type": "transactional",
    "description": "Order confirmations and receipts"
  }'
GET /v?/message-streams

Mengambil semua message streams.

Response (200)
{
  "data": [
    {
      "_id": "ms_001",
      "name": "Transactional Emails",
      "type": "transactional",
      "description": "Order confirmations and receipts",
      "active": true,
      "createdAt": "2026-04-10T10:00:00Z",
      "updatedAt": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/message-streams' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/message-streams/:id

Mengambil detail message stream berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "ms_001",
    "name": "Transactional Emails",
    "type": "transactional",
    "description": "Order confirmations and receipts",
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/message-streams/ms_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/message-streams/:id

Mengupdate message stream berdasarkan ID.

Request Body
{
  "name": "Marketing Emails",
  "type": "marketing",
  "description": "Promotional campaigns",
  "active": true
}
Response (200)
{
  "data": {
    "_id": "ms_001",
    "name": "Marketing Emails",
    "type": "marketing",
    "description": "Promotional campaigns",
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:05:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/message-streams/ms_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Marketing Emails",
    "type": "marketing",
    "description": "Promotional campaigns",
    "active": true
  }'
POST /v?/message-streams/:id/archive

Mengarsipkan message stream.

Response (200)
{
  "message": "Stream archived"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/message-streams/ms_001/archive' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/message-streams/:id/unarchive

Mengembalikan message stream dari arsip.

Response (200)
{
  "message": "Stream unarchived"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/message-streams/ms_001/unarchive' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Snippets

5 endpoints

Save reusable content blocks (HTML and text) that can be inserted into multiple templates — headers, footers, CTAs.

POST /v?/snippets

Membuat snippet (reusable content block) baru.

Request Body
{
  "name": "Footer CTA",
  "html": "<div class='cta'><a href='#'>Sign Up Now</a></div>",
  "text": "Sign Up Now: https://example.com"
}
Response (201)
{
  "data": {
    "_id": "snp_001",
    "name": "Footer CTA",
    "html": "<div class='cta'><a href='#'>Sign Up Now</a></div>",
    "text": "Sign Up Now: https://example.com",
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/snippets' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Footer CTA",
    "html": "<div class=\"cta\"><a href=\"#\">Sign Up Now</a></div>",
    "text": "Sign Up Now: https://example.com"
  }'
GET /v?/snippets

Mengambil semua snippets (tanpa pagination).

Response (200)
{
  "data": [
    {
      "_id": "snp_001",
      "name": "Footer CTA",
      "html": "<div class='cta'><a href='#'>Sign Up Now</a></div>",
      "text": "Sign Up Now: https://example.com",
      "createdAt": "2026-04-10T10:00:00Z",
      "updatedAt": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/snippets' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/snippets/:id

Mengambil detail snippet berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "snp_001",
    "name": "Footer CTA",
    "html": "<div class='cta'><a href='#'>Sign Up Now</a></div>",
    "text": "Sign Up Now: https://example.com",
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/snippets/snp_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/snippets/:id

Mengupdate snippet berdasarkan ID.

Request Body
{
  "name": "Updated Footer CTA",
  "html": "<div class='cta'><a href='#'>Get Started</a></div>"
}
Response (200)
{
  "data": {
    "_id": "snp_001",
    "name": "Updated Footer CTA",
    "html": "<div class='cta'><a href='#'>Get Started</a></div>",
    "text": "Sign Up Now: https://example.com",
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:05:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/snippets/snp_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Updated Footer CTA",
    "html": "<div class=\"cta\"><a href=\"#\">Get Started</a></div>"
  }'
DELETE /v?/snippets/:id

Menghapus snippet berdasarkan ID.

Response (200)
{
  "message": "Snippet deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/snippets/snp_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Template Versions

5 endpoints

Manage template version history. Preview with substitution data, validate HTML, and rollback to previous versions.

GET /v?/templates/:id/versions

Mengambil daftar semua versi dari sebuah template.

Response (200)
{
  "data": [
    {
      "_id": "ver_003",
      "templateId": "tpl_001",
      "version": 3,
      "html": "<html>...</html>",
      "createdAt": "2026-04-10T10:00:00Z",
      "createdBy": "user@example.com"
    },
    {
      "_id": "ver_002",
      "templateId": "tpl_001",
      "version": 2,
      "html": "<html>...</html>",
      "createdAt": "2026-04-09T10:00:00Z",
      "createdBy": "user@example.com"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/templates/tpl_001/versions' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/templates/:id/versions/:versionId

Mengambil detail versi template tertentu.

Response (200)
{
  "data": {
    "_id": "ver_002",
    "templateId": "tpl_001",
    "version": 2,
    "html": "<html>...</html>",
    "createdAt": "2026-04-09T10:00:00Z",
    "createdBy": "user@example.com"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/templates/tpl_001/versions/ver_002' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/templates/:id/versions/:versionId/rollback

Rollback template ke versi tertentu.

Response (200)
{
  "message": "Template rolled back to version"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/templates/tpl_001/versions/ver_002/rollback' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/templates/:id/preview

Preview template dengan substitution data (merge tags).

Request Body
{
  "substitutionData": {
    "name": "John Doe",
    "company": "Acme Corp"
  }
}
Response (200)
{
  "data": {
    "renderedHtml": "<html><body>Hello John Doe from Acme Corp</body></html>"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/templates/tpl_001/preview' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "substitutionData": {
      "name": "John Doe",
      "company": "Acme Corp"
    }
  }'
POST /v?/templates/validate

Validasi HTML dan subject template tanpa menyimpan.

Request Body
{
  "html": "<html><body>{{name}}, welcome!</body></html>",
  "subject": "Welcome {{name}}"
}
Response (200)
{
  "data": {
    "valid": true,
    "errors": []
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/templates/validate' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "html": "<html><body>{{name}}, welcome!</body></html>",
    "subject": "Welcome {{name}}"
  }'

Designs

9 endpoints

Create and manage email designs (templates with HTML/text content). Includes prebuilt designs you can duplicate and customize.

GET /v?/designs

Mengambil daftar designs dengan pagination. Design: `{_id, name, htmlContent, textContent, subject, category, thumbnailUrl, createdAt, updatedAt}`. Response includes `meta`.

POST /v?/designs

Membuat design baru. Body: `{name, htmlContent, textContent, subject, category}`. Response (201).

GET /v?/designs/:id

Mengambil design by ID. Error: 404=DESIGN_NOT_FOUND

PUT /v?/designs/:id

Mengupdate design. Error: 404=DESIGN_NOT_FOUND

DELETE /v?/designs/:id

Menghapus design. Response: `{"message": "Design deleted"}`. Error: 404=DESIGN_NOT_FOUND

POST /v?/designs/:id/duplicate

Menduplikasi design. Response (201). Error: 404=DESIGN_NOT_FOUND

GET /v?/designs/prebuilt

Mengambil semua prebuilt designs (tanpa pagination).

GET /v?/designs/prebuilt/:id

Mengambil prebuilt design by ID. Error: 404=DESIGN_NOT_FOUND

POST /v?/designs/prebuilt/:id/duplicate

Menduplikasi prebuilt design ke user designs. Response (201). Error: 404=DESIGN_NOT_FOUND

Single Sends

11 endpoints

Create one-time email sends with full campaign features: design selection, list targeting, scheduling, and duplication.

GET /v?/single-sends

List dengan pagination. SingleSend: `{_id, name, subject, status, senderId, listIds[], segmentIds[], designId, sendAt, createdAt, updatedAt}`

POST /v?/single-sends

Membuat single send baru. Body: `{name, subject, senderId, listIds, segmentIds, designId}`. Response (201).

GET /v?/single-sends/:id

Get by ID. Error: 404=SINGLE_SEND_NOT_FOUND

PUT /v?/single-sends/:id

Update. Error: 404=SINGLE_SEND_NOT_FOUND

DELETE /v?/single-sends/:id

Delete. Response: `{"message": "Single send deleted"}`. Error: 404=SINGLE_SEND_NOT_FOUND

POST /v?/single-sends/:id/duplicate

Duplicate. Response (201). Error: 404=SINGLE_SEND_NOT_FOUND

DELETE /v?/single-sends/bulk

Bulk delete. Body: `{"ids": ["id1","id2"]}`. Response: `{"message": "Single sends deleted"}`

POST /v?/single-sends/:id/schedule

Schedule pengiriman. Body: `{"sendAt": "2026-04-15T10:00:00Z"}`.

POST /v?/single-sends/:id/unschedule

Batalkan schedule.

GET /v?/single-sends/search?q=keyword

Search single sends by keyword.

GET /v?/single-sends/categories

Mengambil daftar categories (string array).

Sending Queues

3 endpoints

Monitor the sending queue status (regular and scheduled). Purge scheduled queue or resend failed messages.

GET /v?/sending-queues

Mengambil snapshot kondisi sending queue saat ini (regular dan scheduled).

Response (200)
{
  "data": {
    "regular": {
      "pending": 120,
      "processing": 15,
      "failed": 3
    },
    "scheduled": {
      "pending": 45,
      "processing": 0,
      "failed": 0
    }
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/sending-queues' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
DELETE /v?/sending-queues/scheduled

Menghapus semua pesan di scheduled queue (purge).

Response (200)
{
  "message": "Scheduled queue purged"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/sending-queues/scheduled' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/sending-queues/resend

Mengirim ulang pesan yang gagal berdasarkan message ID.

Request Body
{
  "messageId": "msg_001"
}
Response (200)
{
  "message": "Message resent"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/sending-queues/resend' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "messageId": "msg_001"
  }'

Contacts

5 endpoints

Store and manage your email recipients. Add, update, search, and delete contacts with custom fields and metadata.

POST /v1/contacts

Membuat contact baru.

Request Body
{
  "email": "alice@example.com",
  "name": "Alice Tan",
  "firstname": "Alice",
  "lastname": "Tan",
  "dayOfBirth": "1995-06-12",
  "gender": "FEMALE",
  "phone": "+628123456789",
  "city": "Jakarta",
  "country": "Indonesia",
  "note": "Lead from enterprise form",
  "company": "Mailtarget",
  "customPeriod": [],
  "customField": {
    "source": "landing-page"
  },
  "labels": [
    "enterprise",
    "trial"
  ],
  "segments": [
    "segment-a"
  ],
  "index": "contacts-main",
  "state": "ACTIVE",
  "deletedState": "ACTIVE",
  "tester": false,
  "unsubscribeReason": "",
  "unsubscribeOrigin": "",
  "funnel": "sales",
  "subscribeSource": {
    "channel": "CONTACT_BOOK",
    "id": "book-001",
    "name": "Main Contact Book"
  },
  "campaigns": [],
  "scenarios": []
}
Response (201)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48101",
    "email": "alice@example.com",
    "createdAt": "2026-04-10T08:00:00Z",
    "name": "Alice Tan",
    "firstname": "Alice",
    "lastname": "Tan",
    "dayOfBirth": "1995-06-12",
    "gender": "FEMALE",
    "phone": "+628123456789",
    "city": "Jakarta",
    "country": "Indonesia",
    "note": "Lead from enterprise form",
    "company": "Mailtarget",
    "customPeriod": [],
    "customField": {
      "source": "landing-page"
    },
    "labels": [
      "enterprise",
      "trial"
    ],
    "segments": [
      "segment-a"
    ],
    "index": "contacts-main",
    "state": "ACTIVE",
    "deletedState": "ACTIVE",
    "tester": false,
    "unsubscribeReason": "",
    "unsubscribeOrigin": "",
    "funnel": "sales",
    "subscribeSource": {
      "channel": "CONTACT_BOOK",
      "id": "book-001",
      "name": "Main Contact Book"
    },
    "campaigns": [],
    "scenarios": []
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/contacts' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "alice@example.com",
    "name": "Alice Tan",
    "firstname": "Alice",
    "lastname": "Tan",
    "city": "Jakarta",
    "country": "Indonesia",
    "labels": ["enterprise"],
    "state": "ACTIVE",
    "deletedState": "ACTIVE",
    "tester": false
  }'
GET /v1/contacts

Mengambil daftar contact dengan pagination dan pencarian sederhana.

Response (200)
{
  "data": [
    {
      "_id": "66167a2b4f9b72a5c2f48101",
      "email": "alice@example.com",
      "createdAt": "2026-04-10T08:00:00Z",
      "name": "Alice Tan",
      "firstname": "Alice",
      "lastname": "Tan",
      "dayOfBirth": "1995-06-12",
      "gender": "FEMALE",
      "phone": "+628123456789",
      "city": "Jakarta",
      "country": "Indonesia",
      "note": "Lead from enterprise form",
      "company": "Mailtarget",
      "customPeriod": [],
      "customField": {
        "source": "landing-page"
      },
      "labels": [
        "enterprise",
        "trial"
      ],
      "segments": [
        "segment-a"
      ],
      "index": "contacts-main",
      "state": "ACTIVE",
      "deletedState": "ACTIVE",
      "tester": false,
      "unsubscribeReason": "",
      "unsubscribeOrigin": "",
      "funnel": "sales",
      "subscribeSource": {
        "channel": "CONTACT_BOOK",
        "id": "book-001",
        "name": "Main Contact Book"
      },
      "campaigns": [],
      "scenarios": []
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/contacts?page=1&perPage=20&search=alice' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v1/contacts/:id

Mengambil detail satu contact berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48101",
    "email": "alice@example.com",
    "createdAt": "2026-04-10T08:00:00Z",
    "name": "Alice Tan",
    "firstname": "Alice",
    "lastname": "Tan",
    "dayOfBirth": "1995-06-12",
    "gender": "FEMALE",
    "phone": "+628123456789",
    "city": "Jakarta",
    "country": "Indonesia",
    "note": "Lead from enterprise form",
    "company": "Mailtarget",
    "customPeriod": [],
    "customField": {
      "source": "landing-page"
    },
    "labels": [
      "enterprise",
      "trial"
    ],
    "segments": [
      "segment-a"
    ],
    "index": "contacts-main",
    "state": "ACTIVE",
    "deletedState": "ACTIVE",
    "tester": false,
    "unsubscribeReason": "",
    "unsubscribeOrigin": "",
    "funnel": "sales",
    "subscribeSource": {
      "channel": "CONTACT_BOOK",
      "id": "book-001",
      "name": "Main Contact Book"
    },
    "campaigns": [],
    "scenarios": []
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/contacts/66167a2b4f9b72a5c2f48101' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v1/contacts/:id

Memperbarui data contact secara partial berdasarkan ID.

Request Body
{
  "email": "alice.updated@example.com",
  "name": "Alice Updated",
  "city": "Bandung",
  "country": "Indonesia",
  "labels": [
    "enterprise"
  ],
  "customField": {
    "source": "api-update"
  }
}
Response (200)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48101",
    "email": "alice.updated@example.com",
    "createdAt": "2026-04-10T08:00:00Z",
    "name": "Alice Updated",
    "firstname": "Alice",
    "lastname": "Tan",
    "dayOfBirth": "1995-06-12",
    "gender": "FEMALE",
    "phone": "+628123456789",
    "city": "Bandung",
    "country": "Indonesia",
    "note": "Lead from enterprise form",
    "company": "Mailtarget",
    "customPeriod": [],
    "customField": {
      "source": "api-update"
    },
    "labels": [
      "enterprise"
    ],
    "segments": [
      "segment-a"
    ],
    "index": "contacts-main",
    "state": "ACTIVE",
    "deletedState": "ACTIVE",
    "tester": false,
    "unsubscribeReason": "",
    "unsubscribeOrigin": "",
    "funnel": "sales",
    "subscribeSource": {
      "channel": "CONTACT_BOOK",
      "id": "book-001",
      "name": "Main Contact Book"
    },
    "campaigns": [],
    "scenarios": []
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/contacts/66167a2b4f9b72a5c2f48101' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "alice.updated@example.com",
    "name": "Alice Updated",
    "city": "Bandung",
    "country": "Indonesia",
    "labels": ["enterprise"]
  }'
DELETE /v1/contacts/:id

Menghapus contact berdasarkan ID.

Response (200)
{
  "message": "Contact deleted successfully"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/contacts/66167a2b4f9b72a5c2f48101' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Import / Export

3 endpoints

Bulk import contacts from CSV/JSON files and export your contact lists for backup or migration.

POST /v?/contacts/import

Membuat job import contacts secara asynchronous dari payload CSV atau JSON yang di-encode.

Request Body
{
  "format": "csv",
  "data": "ZW1haWwsbmFtZQphbGljZUBleGFtcGxlLmNvbSxBbGljZQ==",
  "labelIds": [
    "66167a2b4f9b72a5c2f48201"
  ]
}
Response (202)
{
  "data": {
    "_id": "imp_001",
    "status": "pending",
    "totalRows": 0,
    "imported": 0,
    "skipped": 0,
    "failed": 0,
    "labelIds": [
      "66167a2b4f9b72a5c2f48201"
    ],
    "createdAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/contacts/import' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "format": "csv",
    "data": "ZW1haWwsbmFtZQphbGljZUBleGFtcGxlLmNvbSxBbGljZQ==",
    "labelIds": ["66167a2b4f9b72a5c2f48201"]
  }'
POST /v?/contacts/export

Membuat job export contacts secara asynchronous berdasarkan filter yang diberikan.

Request Body
{
  "format": "csv",
  "labelIds": [
    "66167a2b4f9b72a5c2f48201"
  ],
  "query": "jakarta"
}
Response (202)
{
  "data": {
    "_id": "exp_001",
    "status": "pending",
    "totalRows": 0,
    "format": "csv",
    "createdAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/contacts/export' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "format": "csv",
    "labelIds": ["66167a2b4f9b72a5c2f48201"],
    "query": "jakarta"
  }'
GET /v?/contacts/export/:id

Mengambil status export job dan download URL jika file sudah selesai dibuat.

Response (200)
{
  "data": {
    "_id": "exp_001",
    "status": "completed",
    "totalRows": 500,
    "format": "csv",
    "downloadUrl": "https://storage.mailtarget.co/exports/exp_001.csv",
    "createdAt": "2026-04-10T08:00:00Z",
    "completedAt": "2026-04-10T08:02:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/contacts/export/exp_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Labels

5 endpoints

Organize contacts into color-coded groups for easier targeting and segmentation.

POST /v?/labels

Membuat label baru untuk grouping contact.

Request Body
{
  "name": "VIP",
  "description": "Contacts with high purchase intent",
  "color": "#FF6B6B"
}
Response (201)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48201",
    "name": "VIP",
    "description": "Contacts with high purchase intent",
    "color": "#FF6B6B",
    "contactCount": 0,
    "createdAt": "2026-04-10T08:00:00Z",
    "updatedAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/labels' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "VIP",
    "description": "Contacts with high purchase intent",
    "color": "#FF6B6B"
  }'
GET /v?/labels

Mengambil daftar label dengan pagination dan pencarian sederhana.

Response (200)
{
  "data": [
    {
      "_id": "66167a2b4f9b72a5c2f48201",
      "name": "VIP",
      "description": "Contacts with high purchase intent",
      "color": "#FF6B6B",
      "contactCount": 42,
      "createdAt": "2026-04-10T08:00:00Z",
      "updatedAt": "2026-04-10T08:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/labels?page=1&perPage=20&search=vip' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/labels/:id

Mengambil detail satu label berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48201",
    "name": "VIP",
    "description": "Contacts with high purchase intent",
    "color": "#FF6B6B",
    "contactCount": 42,
    "createdAt": "2026-04-10T08:00:00Z",
    "updatedAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/labels/66167a2b4f9b72a5c2f48201' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/labels/:id

Memperbarui label secara partial berdasarkan ID.

Request Body
{
  "name": "VIP Customers",
  "description": "Updated label description",
  "color": "#4ECDC4"
}
Response (200)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48201",
    "name": "VIP Customers",
    "description": "Updated label description",
    "color": "#4ECDC4",
    "contactCount": 42,
    "createdAt": "2026-04-10T08:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/labels/66167a2b4f9b72a5c2f48201' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "VIP Customers",
    "description": "Updated label description",
    "color": "#4ECDC4"
  }'
DELETE /v?/labels/:id

Menghapus label berdasarkan ID.

Response (200)
{
  "data": {
    "deleted": true
  }
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/labels/66167a2b4f9b72a5c2f48201' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Segments

5 endpoints

Create dynamic contact groups based on rules and conditions (e.g. opened last campaign, location, custom field values).

POST /v?/segments

Membuat segment baru untuk grouping contact berbasis rules.

Request Body
{
  "name": "Active Jakarta Contacts",
  "description": "Contacts from Jakarta with active subscription",
  "rules": [
    {
      "field": "city",
      "operator": "equals",
      "value": "Jakarta"
    },
    {
      "field": "state",
      "operator": "equals",
      "value": "ACTIVE"
    }
  ]
}
Response (201)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48301",
    "name": "Active Jakarta Contacts",
    "description": "Contacts from Jakarta with active subscription",
    "rules": [
      {
        "field": "city",
        "operator": "equals",
        "value": "Jakarta"
      }
    ],
    "contactCount": 0,
    "createdAt": "2026-04-10T08:00:00Z",
    "updatedAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/segments' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Active Jakarta Contacts",
    "description": "Contacts from Jakarta with active subscription",
    "rules": [
      {
        "field": "city",
        "operator": "equals",
        "value": "Jakarta"
      }
    ]
  }'
GET /v?/segments

Mengambil daftar segment dengan pagination dan pencarian sederhana.

Response (200)
{
  "data": [
    {
      "_id": "66167a2b4f9b72a5c2f48301",
      "name": "Active Jakarta Contacts",
      "description": "Contacts from Jakarta with active subscription",
      "rules": [
        {
          "field": "city",
          "operator": "equals",
          "value": "Jakarta"
        }
      ],
      "contactCount": 128,
      "createdAt": "2026-04-10T08:00:00Z",
      "updatedAt": "2026-04-10T08:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/segments?page=1&perPage=20&search=jakarta' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/segments/:id

Mengambil detail satu segment berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48301",
    "name": "Active Jakarta Contacts",
    "description": "Contacts from Jakarta with active subscription",
    "rules": [
      {
        "field": "city",
        "operator": "equals",
        "value": "Jakarta"
      }
    ],
    "contactCount": 128,
    "createdAt": "2026-04-10T08:00:00Z",
    "updatedAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/segments/66167a2b4f9b72a5c2f48301' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/segments/:id

Memperbarui segment secara partial berdasarkan ID.

Request Body
{
  "name": "High Value Jakarta Contacts",
  "description": "Updated segment description",
  "rules": [
    {
      "field": "city",
      "operator": "equals",
      "value": "Jakarta"
    },
    {
      "field": "tester",
      "operator": "equals",
      "value": false
    }
  ]
}
Response (200)
{
  "data": {
    "_id": "66167a2b4f9b72a5c2f48301",
    "name": "High Value Jakarta Contacts",
    "description": "Updated segment description",
    "rules": [
      {
        "field": "city",
        "operator": "equals",
        "value": "Jakarta"
      }
    ],
    "contactCount": 128,
    "createdAt": "2026-04-10T08:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/segments/66167a2b4f9b72a5c2f48301' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "High Value Jakarta Contacts",
    "description": "Updated segment description",
    "rules": [
      {
        "field": "city",
        "operator": "equals",
        "value": "Jakarta"
      }
    ]
  }'
DELETE /v?/segments/:id

Menghapus segment berdasarkan ID.

Response (200)
{
  "data": {
    "deleted": true
  }
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/segments/66167a2b4f9b72a5c2f48301' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Recipient Lists

5 endpoints

Create named lists of email addresses for quick targeting. Useful for one-off sends to specific groups.

POST /v?/recipient-lists

Membuat recipient list baru.

Request Body
{
  "name": "Newsletter Subscribers",
  "description": "Active newsletter recipients",
  "recipients": ["user1@example.com", "user2@example.com"]
}
Response (201)
{
  "data": {
    "_id": "rl_001",
    "name": "Newsletter Subscribers",
    "description": "Active newsletter recipients",
    "totalCount": 2,
    "recipients": ["user1@example.com", "user2@example.com"],
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/recipient-lists' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Newsletter Subscribers",
    "description": "Active newsletter recipients",
    "recipients": ["user1@example.com", "user2@example.com"]
  }'
GET /v?/recipient-lists

Mengambil daftar recipient lists dengan pagination dan search.

Response (200)
{
  "data": [
    {
      "_id": "rl_001",
      "name": "Newsletter Subscribers",
      "description": "Active newsletter recipients",
      "totalCount": 2,
      "createdAt": "2026-04-10T10:00:00Z",
      "updatedAt": "2026-04-10T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/recipient-lists?page=1&perPage=20&search=newsletter' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/recipient-lists/:id

Mengambil detail recipient list berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "rl_001",
    "name": "Newsletter Subscribers",
    "description": "Active newsletter recipients",
    "totalCount": 2,
    "recipients": ["user1@example.com", "user2@example.com"],
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/recipient-lists/rl_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/recipient-lists/:id

Mengupdate recipient list berdasarkan ID.

Request Body
{
  "name": "VIP Subscribers",
  "description": "Updated description",
  "recipients": ["user1@example.com", "user3@example.com"]
}
Response (200)
{
  "data": {
    "_id": "rl_001",
    "name": "VIP Subscribers",
    "description": "Updated description",
    "totalCount": 2,
    "recipients": ["user1@example.com", "user3@example.com"],
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:05:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/recipient-lists/rl_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "VIP Subscribers",
    "description": "Updated description",
    "recipients": ["user1@example.com", "user3@example.com"]
  }'
DELETE /v?/recipient-lists/:id

Menghapus recipient list berdasarkan ID.

Response (200)
{
  "message": "Recipient list deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/recipient-lists/rl_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Contact Activity

1 endpoint

View the complete engagement history of a specific contact: every email sent, opened, clicked, and bounced.

GET /v?/contacts/:id/activity

Mengambil activity log (events) untuk contact tertentu dengan pagination.

Response (200)
{
  "data": [
    {
      "event": "open",
      "timestamp": "2026-04-10T10:00:00Z",
      "campaignId": "cmp_001",
      "messageId": "msg_001",
      "metadata": {
        "userAgent": "Mozilla/5.0",
        "ip": "203.0.113.1"
      }
    },
    {
      "event": "click",
      "timestamp": "2026-04-10T10:01:00Z",
      "campaignId": "cmp_001",
      "messageId": "msg_001",
      "metadata": {
        "url": "https://example.com/promo"
      }
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 2
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/contacts/cnt_001/activity?page=1&perPage=20' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Mailing Lists

11 endpoints

Create and manage mailing lists with addresses, member management, and bulk operations.

GET /v?/mailing-lists

Mengambil daftar mailing lists dengan pagination.

Response (200)
{
  "data": [
    {
      "_id": "ml_001",
      "address": "newsletter@lists.example.com",
      "name": "Newsletter",
      "description": "Monthly newsletter",
      "memberCount": 1500,
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "perPage": 20, "total": 1 }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/mailing-lists?page=1&perPage=20' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/mailing-lists

Membuat mailing list baru.

Request Body
{
  "address": "newsletter@lists.example.com",
  "name": "Newsletter",
  "description": "Monthly newsletter"
}
Response (201)
{
  "data": {
    "_id": "ml_001",
    "address": "newsletter@lists.example.com",
    "name": "Newsletter",
    "description": "Monthly newsletter",
    "memberCount": 0,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
GET /v?/mailing-lists/:id

Mengambil detail mailing list berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "ml_001",
    "address": "newsletter@lists.example.com",
    "name": "Newsletter",
    "description": "Monthly newsletter",
    "memberCount": 1500,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
PUT /v?/mailing-lists/:id

Mengupdate mailing list.

Request Body
{
  "name": "Updated Newsletter",
  "description": "Weekly newsletter"
}
Response (200)
{
  "data": {
    "_id": "ml_001",
    "address": "newsletter@lists.example.com",
    "name": "Updated Newsletter",
    "description": "Weekly newsletter",
    "memberCount": 1500,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
DELETE /v?/mailing-lists/:id

Menghapus mailing list.

Response (200)
{
  "message": "Mailing list deleted"
}
GET /v?/mailing-lists/:id/members

Mengambil daftar members dari mailing list dengan pagination.

Response (200)
{
  "data": [
    {
      "email": "user@example.com",
      "name": "John Doe",
      "vars": { "company": "Acme" },
      "subscribed": true,
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "perPage": 20, "total": 1 }
}
POST /v?/mailing-lists/:id/members

Menambahkan member ke mailing list.

Request Body
{
  "email": "user@example.com",
  "name": "John Doe",
  "vars": { "company": "Acme" }
}
Response (201)
{
  "data": {
    "email": "user@example.com",
    "name": "John Doe",
    "vars": { "company": "Acme" },
    "subscribed": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
POST /v?/mailing-lists/:id/members/bulk

Bulk add members ke mailing list.

Request Body
{
  "members": [
    { "email": "user1@example.com", "name": "User 1" },
    { "email": "user2@example.com", "name": "User 2" }
  ]
}
Response (202)
{
  "data": {
    "added": 2,
    "skipped": 0
  }
}
GET /v?/mailing-lists/:id/members/:email

Mengambil detail member dari mailing list.

Response (200)
{
  "data": {
    "email": "user@example.com",
    "name": "John Doe",
    "vars": { "company": "Acme" },
    "subscribed": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
PUT /v?/mailing-lists/:id/members/:email

Mengupdate member mailing list.

Request Body
{
  "name": "Updated Name",
  "subscribed": false
}
Response (200)
{
  "data": {
    "email": "user@example.com",
    "name": "Updated Name",
    "vars": { "company": "Acme" },
    "subscribed": false,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
DELETE /v?/mailing-lists/:id/members/:email

Menghapus member dari mailing list.

Response (200)
{
  "message": "Member removed"
}

Custom Fields

4 endpoints

Define custom data fields for contacts beyond the defaults (e.g. company, industry, plan). Used for personalization and segmentation.

GET /v?/custom-fields

Mengambil semua custom field definitions. CustomFieldDef: `{_id, name, fieldType, createdAt}`

Response (200)
{
  "data": [
    { "_id": "cf_001", "name": "company", "fieldType": "text", "createdAt": "2026-04-10T10:00:00Z" }
  ]
}
POST /v?/custom-fields

Membuat custom field baru. Body: `{name, fieldType}`. Default fieldType="text". Validation: NAME_REQUIRED.

Response (201)
{
  "data": { "_id": "cf_002", "name": "industry", "fieldType": "text", "createdAt": "2026-04-10T10:00:00Z" }
}
PUT /v?/custom-fields/:id

Update custom field. Body: `{name, fieldType}`. Error: 404=CUSTOM_FIELD_NOT_FOUND

DELETE /v?/custom-fields/:id

Delete custom field. Response: `{"message": "Custom field deleted"}`. Error: 404=CUSTOM_FIELD_NOT_FOUND

Webhooks

3 endpoints

Receive real-time event notifications (delivered, opened, clicked, bounced, etc.) via HTTP callbacks to your server.

POST /v?/webhooks
cURL Example 
curl -X POST https://apiconfig.mailtarget.co/v?/webhooks \
  -H "Authorization: Bearer MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delivery notifications",
    "targetUrl": "https://example.com/webhook",
    "eventIds": [1, 3]
  }'
GET /v?/webhooks
cURL Example 
curl -X GET "https://apiconfig.mailtarget.co/v?/webhooks?page=1&perPage=20" \
  -H "Authorization: Bearer MAILTARGET_API_KEY"
DELETE /v?/webhooks/:id
cURL Example 
curl -X DELETE https://apiconfig.mailtarget.co/v?/webhooks/42 \
  -H "Authorization: Bearer MAILTARGET_API_KEY"

Webhook Testing

2 endpoints

Send test events to your webhook URLs to verify they are correctly configured before going live.

POST /v?/webhooks/:id/test

Mengirim test event ke webhook URL untuk memverifikasi konfigurasi.

Response (200)
{
  "data": {
    "webhookId": "wh_001",
    "testStatus": "success",
    "responseCode": 200,
    "responseTime": 120,
    "sentAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/webhooks/wh_001/test' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/webhooks/:id/batch-status

Mengambil status batch delivery webhook (jumlah pending, delivered, failed).

Response (200)
{
  "data": {
    "webhookId": "wh_001",
    "pending": 5,
    "delivered": 142,
    "failed": 3,
    "lastDelivered": "2026-04-10T09:55:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/webhooks/wh_001/batch-status' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Relay Webhooks

5 endpoints

Forward incoming emails to your application. Configure which inbound domains relay to which webhook URLs.

POST /v?/relay-webhooks

Membuat relay webhook baru untuk forwarding inbound email ke URL tertentu.

Request Body
{
  "name": "Support Relay",
  "domain": "inbound.example.com",
  "targetUrl": "https://app.example.com/webhooks/inbound",
  "authToken": "secret-token-123"
}
Response (201)
{
  "data": {
    "_id": "rw_001",
    "name": "Support Relay",
    "domain": "inbound.example.com",
    "targetUrl": "https://app.example.com/webhooks/inbound",
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/relay-webhooks' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Support Relay",
    "domain": "inbound.example.com",
    "targetUrl": "https://app.example.com/webhooks/inbound",
    "authToken": "secret-token-123"
  }'
GET /v?/relay-webhooks

Mengambil semua relay webhooks.

Response (200)
{
  "data": [
    {
      "_id": "rw_001",
      "name": "Support Relay",
      "domain": "inbound.example.com",
      "targetUrl": "https://app.example.com/webhooks/inbound",
      "active": true,
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/relay-webhooks' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/relay-webhooks/:id

Mengambil detail relay webhook berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "rw_001",
    "name": "Support Relay",
    "domain": "inbound.example.com",
    "targetUrl": "https://app.example.com/webhooks/inbound",
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/relay-webhooks/rw_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/relay-webhooks/:id

Mengupdate relay webhook.

Request Body
{
  "name": "Updated Relay",
  "targetUrl": "https://app.example.com/webhooks/v2/inbound",
  "active": false
}
Response (200)
{
  "data": {
    "_id": "rw_001",
    "name": "Updated Relay",
    "domain": "inbound.example.com",
    "targetUrl": "https://app.example.com/webhooks/v2/inbound",
    "active": false,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/relay-webhooks/rw_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Updated Relay",
    "targetUrl": "https://app.example.com/webhooks/v2/inbound",
    "active": false
  }'
DELETE /v?/relay-webhooks/:id

Menghapus relay webhook.

Response (200)
{
  "message": "Relay webhook deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/relay-webhooks/rw_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Webhook Security

7 endpoints

Manage HMAC signing policies for webhook payloads. Verify webhook authenticity and prevent spoofing.

GET /v?/webhooks/security

Mengambil semua security policies. Policy: `{_id, name, enabled, createdAt}` (signingKey hanya via dedicated `/signing-key` route)

POST /v?/webhooks/security

Membuat security policy baru. Body: `{name, enabled}`. Response (201).

GET /v?/webhooks/security/:id

Get by ID. Error: 404=WEBHOOK_SECURITY_POLICY_NOT_FOUND

PUT /v?/webhooks/security/:id

Update policy. Error: 404=WEBHOOK_SECURITY_POLICY_NOT_FOUND

DELETE /v?/webhooks/security/:id

Delete policy. Response: `{"message": "Security policy deleted"}`. Error: 404=WEBHOOK_SECURITY_POLICY_NOT_FOUND

GET /v?/webhooks/security/:id/signing-key

Mengambil HMAC signing key untuk policy.

PATCH /v?/webhooks/security/:id/signing-key

Toggle/update webhook signing. Body: `{enabled: true}`

Webhook Egress

3 endpoints

Configure outbound webhook delivery behavior: rate limiting, batching, retry policies, and delivery statistics.

GET /v?/webhooks/egress-config

Mengambil konfigurasi webhook egress (rate limiting, batching, retry).

Response (200)
{
  "data": {
    "maxPerSecond": 100,
    "batchingEnabled": true,
    "batchSize": 50,
    "batchWindowMs": 5000,
    "retryEnabled": true,
    "maxRetries": 5,
    "retryBackoffMs": 1000
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/webhooks/egress-config' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PATCH /v?/webhooks/egress-config

Mengupdate konfigurasi webhook egress.

Request Body
{
  "maxPerSecond": 200,
  "batchingEnabled": true,
  "batchSize": 100,
  "batchWindowMs": 3000,
  "retryEnabled": true,
  "maxRetries": 3,
  "retryBackoffMs": 2000
}
Response (200)
{
  "data": {
    "maxPerSecond": 200,
    "batchingEnabled": true,
    "batchSize": 100,
    "batchWindowMs": 3000,
    "retryEnabled": true,
    "maxRetries": 3,
    "retryBackoffMs": 2000
  }
}
cURL Example 
curl --request PATCH 'https://api.mailtarget.co/v1/webhooks/egress-config' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "maxPerSecond": 200,
    "batchingEnabled": true,
    "batchSize": 100,
    "batchWindowMs": 3000,
    "retryEnabled": true,
    "maxRetries": 3,
    "retryBackoffMs": 2000
  }'
GET /v?/webhooks/egress-stats

Mengambil statistik webhook egress (delivery rates, failures, queue depth).

Response (200)
{
  "data": {
    "totalDelivered": 15230,
    "totalFailed": 42,
    "totalPending": 8,
    "avgLatencyMs": 120,
    "successRate": 99.7
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/webhooks/egress-stats' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Campaign Analytics

2 endpoints

Track campaign performance: open rates, click rates, bounce rates, unsubscribes, and engagement over time.

GET /v?/campaigns/:id/analytics
cURL Example 
curl -X GET https://apiconfig.mailtarget.co/v?/campaigns/663f1a2b4c5d6e7f8a9b0c1d/analytics \
  -H "Authorization: Bearer {API_KEY}"
GET /v?/campaigns/:id/recipients
cURL Example 
curl -X GET "https://apiconfig.mailtarget.co/v?/campaigns/663f1a2b/recipients?page=1&perPage=20&status=bounced" \
  -H "Authorization: Bearer {API_KEY}"

Message Events

2 endpoints

Query the event stream for individual messages: delivery attempts, opens, clicks, bounces, and complaints.

GET /v?/events

Query: `page`, `perPage`, `event` (delivered/opened/clicked/bounced/complained/unsubscribed), `email`, `dateFrom`, `dateTo`, `campaignId`.

GET /v?/events/:messageId

All events for a specific message, ordered chronologically.

Deliverability

3 endpoints

Monitor inbox placement rates, spam folder rates, and domain reputation across major mailbox providers.

GET /v?/deliverability/report

Overall deliverability report.

GET /v?/deliverability/domains

Per-domain breakdown. Query: `page`, `perPage`.

GET /v?/deliverability/reputation

Reputation score + trend. Query: `dateFrom`, `dateTo`.

Stats Aggregate

6 endpoints

Get aggregated sending statistics across all campaigns: total sent, delivered, opened, clicked, bounced over configurable time periods.

GET /v?/stats

Query: `dateFrom`, `dateTo`, `aggregatedBy` (day/week/month).

GET /v?/stats/categories

Stats grouped by transmission category. Same query params.

GET /v?/stats/mailbox-providers

By ISP. `{ "data": [{ "provider": "Gmail", "delivered": 2000, "opens": 900, "inboxRate": 98.5 }] }`

GET /v?/stats/devices

`{ "data": [{ "device": "mobile", "opens": 1200, "clicks": 400, "percentage": 57.1 }] }`

GET /v?/stats/geo

Query: optional `country`. `{ "data": [{ "country": "ID", "city": "Jakarta", "opens": 800, "clicks": 300 }] }`

GET /v?/stats/browsers

`{ "data": [{ "client": "Gmail", "opens": 900, "percentage": 42.8 }, { "client": "Apple Mail", "opens": 500, "percentage": 23.8 }] }`

Advanced Metrics

7 endpoints

Drill down into sending metrics by IP, template, subaccount, bounce reason, delay reason, and link engagement.

GET /v?/metrics/sending-ip

Mengambil breakdown metrics berdasarkan sending IP.

Response (200)
{
  "data": [
    {
      "key": "192.0.2.10",
      "label": "IP Pool A",
      "count": 15230,
      "percentage": 62.3
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/sending-ip?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/metrics/template

Mengambil breakdown metrics berdasarkan template.

Response (200)
{
  "data": [
    {
      "key": "tpl_001",
      "label": "Welcome Email",
      "count": 8420,
      "percentage": 34.5
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/template?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/metrics/subaccount

Mengambil breakdown metrics berdasarkan subaccount.

Response (200)
{
  "data": [
    {
      "key": "sub_001",
      "label": "Marketing Team",
      "count": 12000,
      "percentage": 49.1
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/subaccount?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/metrics/bounce-reasons

Mengambil breakdown alasan bounce.

Response (200)
{
  "data": [
    {
      "key": "550",
      "label": "Mailbox not found",
      "count": 342,
      "percentage": 68.4
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/bounce-reasons?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/metrics/bounce-classifications

Mengambil breakdown klasifikasi bounce (hard, soft, etc.).

Response (200)
{
  "data": [
    {
      "key": "hard",
      "count": 230,
      "percentage": 46.0
    },
    {
      "key": "soft",
      "count": 270,
      "percentage": 54.0
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/bounce-classifications?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/metrics/delay-reasons

Mengambil breakdown alasan delay pengiriman.

Response (200)
{
  "data": [
    {
      "key": "throttled",
      "label": "Remote server throttling",
      "count": 89,
      "percentage": 71.2
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/delay-reasons?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/metrics/link-engagement

Mengambil breakdown link engagement (click per link).

Response (200)
{
  "data": [
    {
      "key": "https://example.com/promo",
      "label": "Promo Link",
      "count": 1523,
      "percentage": 42.8
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/metrics/link-engagement?dateFrom=2026-04-01&dateTo=2026-04-10' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Email Activity

4 endpoints

Search and export detailed message activity — every email sent, with recipient, status, and timestamp.

GET /v?/email-activity/messages

Mencari message activity dengan pagination dan filter.

Response (200)
{
  "data": [
    {
      "id": "msg_001",
      "to": "user@example.com",
      "from": "sender@example.com",
      "subject": "Welcome",
      "status": "delivered",
      "timestamp": "2026-04-10T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "perPage": 20, "total": 1 }
}
GET /v?/email-activity/messages/:id

Mengambil detail message. Error: 404=MESSAGE_NOT_FOUND

POST /v?/email-activity/export

Request export message activity (async). Body: `{to, from, subject, status, dateFrom, dateTo}`.

Response (202)
{
  "data": {
    "downloadId": "exp_001",
    "status": "pending"
  }
}
GET /v?/email-activity/export/:id

Mengambil status export job. Error: 404=MESSAGE_EXPORT_NOT_FOUND

Response (200)
{
  "data": {
    "downloadId": "exp_001",
    "status": "completed",
    "downloadUrl": "https://export.mailtarget.co/exp_001.csv"
  }
}

Engagement Quality

2 endpoints

Get an overall engagement quality score for your account based on open rates, click rates, bounce rates, and complaint rates.

GET /v?/engagement/scores

Mengambil engagement quality scores untuk akun.

Response (200)
{
  "data": {
    "score": 85,
    "metrics": {
      "openRate": 32.5,
      "clickRate": 8.2,
      "bounceRate": 1.1,
      "complaintRate": 0.02
    }
  }
}
GET /v?/engagement/subaccount-scores

Mengambil engagement scores per subaccount.

Response (200)
{
  "data": [
    {
      "subaccountId": "sub_001",
      "name": "Marketing Team",
      "score": 82,
      "openRate": 30.1,
      "clickRate": 7.5
    }
  ]
}

Marketing Stats

8 endpoints

Get aggregated stats for marketing campaigns and automations, including per-link click tracking and CSV exports.

GET /v?/marketing-stats/campaigns

Mengambil stats semua campaigns (array of maps).

GET /v?/marketing-stats/campaigns/:id

Mengambil stats campaign by ID.

GET /v?/marketing-stats/campaigns/:id/links

Mengambil link-level stats untuk campaign.

GET /v?/marketing-stats/automations

Mengambil stats semua automations.

GET /v?/marketing-stats/automations/:id

Mengambil stats automation by ID.

GET /v?/marketing-stats/automations/:id/links

Mengambil link-level stats untuk automation.

POST /v?/marketing-stats/campaigns/export

Export campaign stats (async). Response (202): `{"data": {"downloadId": "...", "status": "pending"}}`

POST /v?/marketing-stats/automations/export

Export automation stats (async). Response (202).

Bounces

1 endpoint

Track hard and soft bounces. Hard bounces are automatically suppressed to protect your sender reputation.

GET /v?/bounces

Mengambil daftar bounced emails dengan filter opsional.

Response (200)
{
  "data": [
    {
      "email": "invalid@example.com",
      "type": "hard",
      "reason": "mailbox does not exist",
      "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
      "bouncedAt": "2026-04-10T08:05:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 15
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/bounces?page=1&perPage=20&type=hard&campaignId=663f1a2b4c5d6e7f8a9b0c1d' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Suppression

2 endpoints

Manage the global suppression list. Addresses on this list will not receive any emails regardless of campaign or list membership.

POST /v?/suppression
DELETE /v?/suppression/:email
cURL Example 
curl -X DELETE https://apiconfig.mailtarget.co/v?/suppression/bounce@example.com \
  -H "Authorization: Bearer {API_KEY}"

Unsubscribes

2 endpoints

View and manage contacts who have opted out of receiving emails. Required for CAN-SPAM and GDPR compliance.

GET /v?/unsubscribes

Mengambil daftar kontak yang sudah unsubscribe.

Response (200)
{
  "data": [
    {
      "email": "user@example.com",
      "reason": "Requested via support",
      "origin": "api",
      "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
      "unsubscribedAt": "2026-04-10T08:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 42
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/unsubscribes?page=1&perPage=20&search=user@example.com' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/unsubscribes

Menambahkan email ke unsubscribe list secara manual.

Request Body
{
  "email": "user@example.com",
  "reason": "Requested via support",
  "campaignId": "663f1a2b4c5d6e7f8a9b0c1d"
}
Response (201)
{
  "data": {
    "email": "user@example.com",
    "reason": "Requested via support",
    "origin": "api",
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d",
    "unsubscribedAt": "2026-04-10T08:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/unsubscribes' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "user@example.com",
    "reason": "Requested via support",
    "campaignId": "663f1a2b4c5d6e7f8a9b0c1d"
  }'

Block List

2 endpoints

Manually block specific email addresses or domains from receiving any emails from your account.

GET /v?/blocks

Query: `page`, `perPage`, `search`.

DELETE /v?/blocks/:email

Response: `{ "message": "Email unblocked" }`

Spam Reports

2 endpoints

View contacts who marked your emails as spam. These addresses are automatically suppressed.

GET /v?/spam-reports

Query: `page`, `perPage`, `dateFrom`, `dateTo`.

DELETE /v?/spam-reports/:email

Response: `{ "message": "Spam report removed" }`

Unsubscribe Groups

8 endpoints

Let contacts opt out of specific email types (marketing, updates, etc.) instead of unsubscribing from everything.

POST /v?/unsubscribe-groups

{ "name": "Marketing", "description": "Marketing emails opt-out" }

GET /v?/unsubscribe-groups

— GET /:id — PUT /:id — DELETE /:id

POST /v?/unsubscribe-groups/:id/emails

Add emails to group. `{ "emails": ["a@b.com", "c@d.com"] }`

GET /v?/unsubscribe-groups/:id/emails

List emails in group. Query: `page`, `perPage`.

DELETE /v?/unsubscribe-groups/:id/emails/:email

Remove email from group.

Bounce Extras

2 endpoints

Access raw bounce diagnostic data and reactivate bounced addresses after fixing the underlying issue.

GET /v?/bounces/:id/dump

Mengambil raw bounce dump (full diagnostic data) berdasarkan bounce ID.

Response (200)
{
  "data": {
    "bounceId": "bnc_001",
    "email": "user@example.com",
    "type": "hard",
    "diagnosticCode": "550 5.1.1 User unknown",
    "mxHost": "mx.example.com",
    "rawHeaders": "...",
    "timestamp": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/bounces/bnc_001/dump' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/bounces/:id/reactivate

Reactivate bounced email — menghapus dari suppression list sehingga bisa dikirim lagi.

Response (200)
{
  "message": "Bounce reactivated"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/bounces/bnc_001/reactivate' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Allowlist

6 endpoints

Maintain a list of email addresses or domains that should always receive emails, bypassing suppression rules.

GET /v?/allowlist

Mengambil daftar allowlist entries dengan pagination.

Response (200)
{
  "data": [
    {
      "value": "user@example.com",
      "type": "email",
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/allowlist?page=1&perPage=20' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/allowlist/:value

Mengambil detail allowlist entry berdasarkan value (email/domain).

Response (200)
{
  "data": {
    "value": "user@example.com",
    "type": "email",
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/allowlist/user@example.com' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/allowlist

Menambahkan entry ke allowlist.

Request Body
{
  "value": "user@example.com",
  "type": "email"
}
Response (201)
{
  "data": {
    "value": "user@example.com",
    "type": "email",
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/allowlist' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "value": "user@example.com",
    "type": "email"
  }'
POST /v?/allowlist/import

Import bulk allowlist entries.

Request Body
{
  "entries": [
    { "value": "user1@example.com", "type": "email" },
    { "value": "example.com", "type": "domain" }
  ]
}
Response (202)
{
  "data": {
    "imported": 2,
    "skipped": 0
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/allowlist/import' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "entries": [
      { "value": "user1@example.com", "type": "email" },
      { "value": "example.com", "type": "domain" }
    ]
  }'
DELETE /v?/allowlist/:value

Menghapus entry dari allowlist.

Response (200)
{
  "message": "Entry removed"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/allowlist/user@example.com' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
DELETE /v?/allowlist

Menghapus semua entries dari allowlist.

Response (200)
{
  "message": "All entries removed"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/allowlist' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Invalid Emails

4 endpoints

View and manage email addresses that failed validation — syntax errors, nonexistent domains, or mailbox issues.

GET /v?/invalid-emails

Mengambil daftar invalid emails dengan pagination. InvalidEmail: `{email, reason, createdAt}`. Response includes `meta`.

GET /v?/invalid-emails/:email

Mengambil invalid email by email address. Error: 404=INVALID_EMAIL_NOT_FOUND. Validation: EMAIL_REQUIRED.

DELETE /v?/invalid-emails/:email

Menghapus satu invalid email. Response: `{"message": "Invalid email removed"}`. Error: 404=INVALID_EMAIL_NOT_FOUND.

DELETE /v?/invalid-emails

Menghapus semua invalid emails. Response: `{"message": "All invalid emails removed"}`

Senders

6 endpoints

Configure the "from" addresses for your emails. Each sender requires domain verification for deliverability.

POST /v?/senders

Create sender identity. Required: `name`, `email`.

GET /v?/senders

Query: `page`, `perPage`, `search`. Response: array + meta.

GET /v?/senders/:id

— PUT /v?/senders/:id — DELETE /v?/senders/:id

POST /v?/senders/:id/verify

Trigger verification email. Response: `{ "message": "Verification email sent" }`

Tracking Domains

5 endpoints

Set up custom domains for click and open tracking links instead of the default Mailtarget domain.

POST /v?/tracking-domains

Required: `domain`.

GET /v?/tracking-domains

— GET /v?/tracking-domains/:id — DELETE /v?/tracking-domains/:id

POST /v?/tracking-domains/:id/verify

Verify CNAME record. Response: updated object with `verified: true` or error.

Alerts

5 endpoints

Configure notifications for important events: quota approaching limit, bounce rate spike, blocklist detection.

POST /v?/alerts

{ "type": "bounce_rate", "threshold": 5.0, "channel": "email" }

GET /v?/alerts

— GET /v?/alerts/:id — PUT /v?/alerts/:id — DELETE /v?/alerts/:id

Integrations

6 endpoints

Connect Mailtarget with third-party services. Manage integration configurations and credentials.

GET /v?/integrations

Mengambil semua integrations. Response: `{"data": [{_id, name, provider, config, active, createdAt}]}`

POST /v?/integrations

Membuat integration baru. Body: `{name, provider, config, active}`. Response (201): `{"data": {...}}`

GET /v?/integrations/:id

Mengambil detail integration. Error: 404=INTEGRATION_NOT_FOUND

PUT /v?/integrations/:id

Mengupdate integration. Error: 404=INTEGRATION_NOT_FOUND

DELETE /v?/integrations/:id

Menghapus integration. Response: `{"message": "Integration deleted"}`. Error: 404=INTEGRATION_NOT_FOUND

DELETE /v?/integrations/bulk

Bulk delete integrations. Body: `{"ids": ["id1","id2"]}`. Response: `{"message": "Integrations deleted"}`

Mail Settings

13 endpoints

Configure account-wide email settings: footer, bounce purge policy, forward bounce/spam, address whitelist, and template defaults.

GET /v?/mail-settings

Mengambil daftar semua mail settings. Response: `{"data": [{name, enabled}]}`

GET /v?/mail-settings/footer

Mengambil footer setting. Response: `{"data": {enabled, htmlBody, textBody}}`

PATCH /v?/mail-settings/footer

Update footer setting. Body: `{enabled, htmlBody, textBody}`

GET /v?/mail-settings/bounce-purge

Mengambil bounce purge setting. Response: `{"data": {enabled, hardBouncesPurgeAfterDays, softBouncesPurgeAfterDays}}`

PATCH /v?/mail-settings/bounce-purge

Update bounce purge. Body: `{enabled, hardBouncesPurgeAfterDays, softBouncesPurgeAfterDays}`

GET /v?/mail-settings/forward-bounce

Mengambil forward bounce setting. Response: `{"data": {enabled, email}}`

PATCH /v?/mail-settings/forward-bounce

Update forward bounce. Body: `{enabled, email}`

GET /v?/mail-settings/forward-spam

Mengambil forward spam setting. Response: `{"data": {enabled, email}}`

PATCH /v?/mail-settings/forward-spam

Update forward spam. Body: `{enabled, email}`

GET /v?/mail-settings/address-whitelist

Mengambil address whitelist config.

PATCH /v?/mail-settings/address-whitelist

Update address whitelist.

GET /v?/mail-settings/template

Mengambil template setting.

PATCH /v?/mail-settings/template

Update template setting.

Tracking Settings

9 endpoints

Enable or disable click tracking, open tracking, Google Analytics UTM parameters, and subscription tracking.

GET /v?/tracking-settings

Mengambil daftar semua tracking settings (array of maps).

GET /v?/tracking-settings/click

Mengambil click tracking config.

PATCH /v?/tracking-settings/click

Update click tracking. Body: `{enabled: true}`

GET /v?/tracking-settings/open

Mengambil open tracking config.

PATCH /v?/tracking-settings/open

Update open tracking.

GET /v?/tracking-settings/google-analytics

Mengambil Google Analytics tracking config.

PATCH /v?/tracking-settings/google-analytics

Update GA tracking. Body: `{enabled, utmSource, utmMedium, utmCampaign}`

GET /v?/tracking-settings/subscription

Mengambil subscription tracking config.

PATCH /v?/tracking-settings/subscription

Update subscription tracking.

Verified Senders

8 endpoints

Register and verify sender identities (from addresses). Required before you can send email from a new address.

GET /v?/verified-senders

Mengambil semua verified senders (array of maps).

POST /v?/verified-senders

Membuat verified sender baru. Body: `{fromEmail, fromName, replyTo, nickname}`. Response (201).

PUT /v?/verified-senders/:id

Mengupdate verified sender.

DELETE /v?/verified-senders/:id

Menghapus verified sender. Response: `{"message": "Verified sender deleted"}`

POST /v?/verified-senders/:id/resend

Mengirim ulang verification email. Response: `{"message": "Verification resent"}`

GET /v?/verified-senders/:id/steps-completed

Mengambil completed verification steps untuk sender.

GET /v?/verified-senders/:id/domain-warnings

Mengambil domain warnings (SPF/DKIM issues) untuk sender.

POST /v?/verified-senders/verify

Verify sender menggunakan token dari email. Body: `{"token": "..."}`. Response: `{"message": "Sender verified"}`

IP Addresses

4 endpoints

Manage your dedicated sending IP addresses, including warmup status and assignment to pools.

GET /v?/ips

Query: `page`, `perPage`, `poolId`, `warmupStatus`.

GET /v?/ips/:id
POST /v?/ips/:id/warmup

Start IP warmup schedule. Response: `{ "data": { "id": 1, "warmupStatus": "in_progress", "warmupStartedAt": "..." } }`

DELETE /v?/ips/:id/warmup

Stop warmup. Response: `{ "message": "Warmup stopped" }`

IP Pools

5 endpoints

Group dedicated IPs into pools and assign them to different sending streams (transactional vs marketing) to isolate reputation.

POST /v?/ip-pools

Create pool. Required: `name`.

GET /v?/ip-pools

— GET /v?/ip-pools/:id — PUT /v?/ip-pools/:id — DELETE /v?/ip-pools/:id

SMTP Credentials

3 endpoints

Generate SMTP username/password pairs for sending email via SMTP relay instead of the REST API.

POST /v?/smtp-credentials

Response (201) — password shown ONLY on creation:

GET /v?/smtp-credentials

List. Password masked.

DELETE /v?/smtp-credentials/:id

Response: `{ "message": "SMTP credential deleted" }`

Domain Auth

4 endpoints

Set up SPF, DKIM, and DMARC authentication for your sending domains to improve deliverability and prevent spoofing.

GET /v?/domain-auth

List all. `{ "data": [{ "id": 1, "domain": "example.com", "spfStatus": "verified", "dkimStatus": "verified", "dmarcStatus": "pending" }] }`

GET /v?/domain-auth/:id

Full details.

POST /v?/domain-auth/:id/verify

Trigger DNS verification. Response: updated status.

GET /v?/domain-auth/:id/dns-records

Get required DNS records to add.

Reverse DNS

5 endpoints

Set up reverse DNS (PTR records) for your dedicated IPs. Improves deliverability by matching IP to your domain.

GET /v?/reverse-dns

Mengambil semua reverse DNS records. ReverseDNS: `{id (int), ip, rdns, subdomain, domain, valid, createdAt}`

POST /v?/reverse-dns

Membuat reverse DNS record baru (no body needed). Response (201).

GET /v?/reverse-dns/:id

Mengambil reverse DNS by ID. Error: 404=REVERSE_DNS_NOT_FOUND

DELETE /v?/reverse-dns/:id

Menghapus reverse DNS. Response: `{"message": "Reverse DNS deleted"}`. Error: 404=REVERSE_DNS_NOT_FOUND

POST /v?/reverse-dns/:id/validate

Memvalidasi reverse DNS record. Response: `{"data": {"valid": true}}`. Error: 404=REVERSE_DNS_NOT_FOUND

Inbound

6 endpoints

Process incoming emails. Mailtarget receives emails on your behalf and forwards the parsed content to your application via webhooks.

POST /v?/inbound/routes

Required: `domain`, `forwardUrl`.

GET /v?/inbound/routes

— PUT /v?/inbound/routes/:id — DELETE /v?/inbound/routes/:id

GET /v?/inbound/messages

Query: `page`, `perPage`, `dateFrom`, `dateTo`.

GET /v?/inbound/messages/:id

Full message: from, to, subject, bodyText, bodyHtml, headers, attachments (with downloadUrl), receivedAt.

Inbound Domains

4 endpoints

Register domains for receiving inbound email. Requires MX record verification.

POST /v?/inbound-domains

Menambahkan domain untuk inbound email processing.

Request Body
{
  "domain": "inbound.example.com"
}
Response (201)
{
  "data": {
    "_id": "ibd_001",
    "domain": "inbound.example.com",
    "mxVerified": false,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/inbound-domains' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "domain": "inbound.example.com"
  }'
GET /v?/inbound-domains

Mengambil semua inbound domains.

Response (200)
{
  "data": [
    {
      "_id": "ibd_001",
      "domain": "inbound.example.com",
      "mxVerified": true,
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/inbound-domains' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/inbound-domains/:id

Mengambil detail inbound domain berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "ibd_001",
    "domain": "inbound.example.com",
    "mxVerified": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/inbound-domains/ibd_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
DELETE /v?/inbound-domains/:id

Menghapus inbound domain.

Response (200)
{
  "message": "Inbound domain deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/inbound-domains/ibd_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Inbound Parse

6 endpoints

Configure how incoming emails are parsed and forwarded. Set up hostname-to-URL routing with spam checking options.

GET /v?/inbound-parse/settings

Mengambil semua parse settings. ParseSetting: `{hostname, url, spamCheck, sendRaw}`

POST /v?/inbound-parse/settings

Membuat parse setting baru. Body: `{hostname, url, spamCheck, sendRaw}`. Validation: hostname required, url required. Response (201).

GET /v?/inbound-parse/settings/:hostname

Mengambil parse setting by hostname. Error: 404=PARSE_SETTING_NOT_FOUND

PUT /v?/inbound-parse/settings/:hostname

Update parse setting. Error: 404=PARSE_SETTING_NOT_FOUND. Validation: HOSTNAME_REQUIRED.

DELETE /v?/inbound-parse/settings/:hostname

Hapus parse setting. Response: `{"message": "Parse setting deleted"}`. Error: 404=PARSE_SETTING_NOT_FOUND

GET /v?/inbound-parse/stats

Mengambil inbound parse statistics (array of maps).

Email Validation

3 endpoints

Validate email addresses before sending to reduce bounces. Checks syntax, MX records, and mailbox existence.

POST /v?/validate/single

Body: `{ "email": "test@example.com" }`

POST /v?/validate/bulk

Body: `{ "emails": ["a@b.com", "c@d.com", ...] }`

GET /v?/validate/bulk/:id

Response (200) when completed:

Email Preview

4 endpoints

Render email templates with sample data to preview how they look before sending.

POST /v?/preview/render

Render HTML with substitution data.

POST /v?/preview/spam-check

{ "html": "<h1>Buy now!!!</h1>", "subject": "FREE OFFER" }

POST /v?/preview/inbox

Preview across email clients. Async.

GET /v?/preview/inbox/:id

{ "data": { "_id": "prev_001", "status": "completed", "screenshots": [{ "client": "Gmail", "device": "desktop", "imageUrl": "https://..." }, { "client": "Apple Mail", "device": "mobile", "imageUrl": "https://..." }] } }

Seed Lists

5 endpoints

Maintain lists of test email addresses used to verify inbox placement across different providers before sending to real contacts.

POST /v?/seed-lists

`{ "name": "Gmail seeds", "emails": ["seed1@gmail.com", "seed2@yahoo.com"] }`

GET /v?/seed-lists

— DELETE /v?/seed-lists/:id

POST /v?/seed-tests

Run inbox placement test.

GET /v?/seed-tests/:id

{ "data": { "_id": "st_001", "status": "completed", "results": [{ "email": "seed1@gmail.com", "provider": "Gmail", "inbox": true, "spam": false, "missing": false }, { "email": "seed2@yahoo.com", "provider": "Yahoo", "inbox": false, "spam": true, "missing": false }], "inboxRate": 50.0 } }

Email Testing

13 endpoints

Test your email HTML for code compatibility, broken links, broken images, accessibility issues, and send test emails.

POST /v?/email-testing/code-analysis

Membuat code analysis baru — menganalisis HTML email untuk compatibility issues.

Request Body
{
  "html": "<html><body>Your email HTML</body></html>"
}
Response (201)
{
  "data": {
    "_id": "ca_001",
    "status": "completed",
    "issues": [],
    "score": 95
  }
}
GET /v?/email-testing/code-analysis/:id

Mengambil hasil code analysis berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "ca_001",
    "status": "completed",
    "issues": [],
    "score": 95
  }
}
GET /v?/email-testing/code-analysis

Mengambil semua code analysis yang pernah dijalankan.

Response (200)
{
  "data": [
    { "_id": "ca_001", "status": "completed", "score": 95 }
  ]
}
POST /v?/email-testing/link-validation

Membuat link validation — mengecek semua link dalam email HTML.

Request Body
{
  "html": "<html><body><a href='https://example.com'>Link</a></body></html>"
}
Response (201)
{
  "data": {
    "_id": "lv_001",
    "status": "completed",
    "totalLinks": 3,
    "brokenLinks": 0
  }
}
GET /v?/email-testing/link-validation/:id

Mengambil hasil link validation.

GET /v?/email-testing/link-validation

Mengambil semua link validations.

POST /v?/email-testing/image-validation

Membuat image validation — mengecek semua gambar dalam email.

Request Body
{
  "html": "<html><body><img src='https://example.com/img.png'/></body></html>"
}
Response (201)
{
  "data": {
    "_id": "iv_001",
    "status": "completed",
    "totalImages": 5,
    "brokenImages": 1
  }
}
GET /v?/email-testing/image-validation/:id

Mengambil hasil image validation.

POST /v?/email-testing/image-optimization

Optimize images dalam email HTML (resize, compress).

Request Body
{
  "html": "<html><body><img src='https://example.com/large.png'/></body></html>"
}
Response (202)
{
  "data": {
    "optimized": 3,
    "totalSaved": "1.2MB"
  }
}
POST /v?/email-testing/accessibility

Membuat accessibility check — mengecek email untuk WCAG compliance.

Request Body
{
  "html": "<html><body>...</body></html>"
}
Response (201)
{
  "data": {
    "_id": "ac_001",
    "status": "completed",
    "issues": [],
    "score": 88
  }
}
GET /v?/email-testing/accessibility/:id

Mengambil hasil accessibility check.

GET /v?/email-testing/accessibility

Mengambil semua accessibility checks.

POST /v?/email-testing/send-test

Mengirim test marketing email ke alamat tertentu.

Request Body
{
  "to": ["test@example.com"],
  "subject": "Test Campaign",
  "html": "<html><body>Preview</body></html>",
  "from": "sender@example.com"
}
Response (200)
{
  "message": "Test email sent"
}

Quotas

2 endpoints

Check your account sending limits, current usage, and remaining quota for the billing period.

GET /v?/quotas

Current quota and rate limit usage.

GET /v?/quotas/history

Usage history. Query: `dateFrom`, `dateTo`, `aggregatedBy` (day/week/month).

Teammates

6 endpoints

Invite team members to your account with role-based access (admin, editor, viewer).

POST /v?/teammates

Invite. `{ "email": "dev@mailtarget.co", "name": "Dev Team", "role": "developer" }`

GET /v?/teammates

— GET /:id — PUT /:id — DELETE /:id

POST /v?/teammates/:id/resend-invite

Response: `{ "message": "Invite resent" }`

Billing

4 endpoints

View your current plan, download invoices, and check usage costs for the billing period.

GET /v?/billing/plan

Mengambil informasi billing plan saat ini.

Response (200)
{
  "data": {
    "name": "Business",
    "type": "monthly",
    "monthlyLimit": 100000,
    "price": 99.00,
    "currency": "USD",
    "billingDate": "2026-05-01"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/billing/plan' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/billing/invoices

Mengambil daftar invoices dengan pagination.

Response (200)
{
  "data": [
    {
      "_id": "inv_001",
      "date": "2026-04-01",
      "amount": 99.00,
      "currency": "USD",
      "status": "paid",
      "pdfUrl": "https://billing.mailtarget.co/invoices/inv_001.pdf"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/billing/invoices?page=1&perPage=20' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/billing/invoices/:id

Mengambil detail invoice berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "inv_001",
    "date": "2026-04-01",
    "amount": 99.00,
    "currency": "USD",
    "status": "paid",
    "pdfUrl": "https://billing.mailtarget.co/invoices/inv_001.pdf"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/billing/invoices/inv_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/billing/usage

Mengambil billing usage (total sent dan cost) untuk periode tertentu.

Response (200)
{
  "data": {
    "totalSent": 45230,
    "totalCost": 45.23
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/billing/usage?dateFrom=2026-04-01&dateTo=2026-04-30' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Subuser Management

6 endpoints

Manage subuser accounts: view reputation scores, sending stats, allocate credits, and assign dedicated IPs.

GET /v?/subusers/reputations

Mengambil reputation scores semua subusers.

GET /v?/subusers/stats

Mengambil sending stats semua subusers.

GET /v?/subusers/monthly-stats

Mengambil monthly stats semua subusers.

GET /v?/subusers/credits

Mengambil credit allocation subusers.

PUT /v?/subusers/credits

Update credit allocation. Body: `{"credits": 10000, "resetDate": "monthly"}`.

PUT /v?/subusers/ips

Update assigned IPs untuk subuser. Body: `["192.0.2.10", "192.0.2.11"]`. Response: array of assigned IPs.

User / Account

9 endpoints

Manage your account profile, email, username, password, and view credit balance.

GET /v?/account

Mengambil account info.

GET /v?/user/profile

Mengambil user profile.

PATCH /v?/user/profile

Update user profile. Body: `{firstName, lastName, ...}`

GET /v?/user/email

Mengambil user email.

PATCH /v?/user/email

Update user email. Body: `{email: "new@example.com"}`

PATCH /v?/user/password

Update password. Body: `{currentPassword, newPassword}`. Response: `{"message": "Password updated"}`

GET /v?/user/username

Mengambil username.

PATCH /v?/user/username

Update username. Body: `{username: "newname"}`

GET /v?/user/credits

Mengambil credit balance.

API Logs

1 endpoint

View detailed logs of all API requests made to your account — method, path, status code, duration, and source IP.

GET /v?/api-logs

Mengambil daftar API request logs dengan pagination dan filter.

Response (200)
{
  "data": [
    {
      "_id": "log_001",
      "method": "POST",
      "path": "/v1/campaigns",
      "statusCode": 500,
      "duration": 245,
      "apiKeyId": 3,
      "ipAddress": "203.0.113.1",
      "timestamp": "2026-04-10T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/api-logs?page=1&perPage=20&method=POST&statusCode=500' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Audit Logs

1 endpoint

Track all account activity: who did what, when, and from which IP. Essential for security audits and compliance.

GET /v?/audit-logs

Mengambil daftar audit logs dengan pagination dan filter.

Response (200)
{
  "data": [
    {
      "_id": "al_001",
      "userId": 42,
      "userEmail": "admin@example.com",
      "action": "delete",
      "resource": "campaign",
      "resourceId": "cmp_001",
      "ipAddress": "203.0.113.1",
      "timestamp": "2026-04-10T10:00:00Z",
      "details": {
        "campaignName": "April Newsletter"
      }
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/audit-logs?page=1&perPage=20&action=delete&dateFrom=2026-04-01' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

IP Access

3 endpoints

Restrict API access to specific IP addresses. Only whitelisted IPs can make API calls to your account.

POST /v?/ip-access

Menambahkan IP address ke whitelist untuk API access.

Request Body
{
  "ip": "203.0.113.50",
  "note": "Office IP"
}
Response (201)
{
  "data": {
    "id": 1,
    "ip": "203.0.113.50",
    "note": "Office IP",
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/ip-access' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "ip": "203.0.113.50",
    "note": "Office IP"
  }'
GET /v?/ip-access

Mengambil semua IP access rules.

Response (200)
{
  "data": [
    {
      "id": 1,
      "ip": "203.0.113.50",
      "note": "Office IP",
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/ip-access' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
DELETE /v?/ip-access/:id

Menghapus IP access rule berdasarkan ID.

Response (200)
{
  "message": "IP access rule deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/ip-access/1' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

SSO

4 endpoints

Configure SAML-based Single Sign-On so your team can log in with your identity provider (Okta, Azure AD, etc.).

POST /v?/sso

Membuat konfigurasi SSO (SAML) baru.

Request Body
{
  "enabled": true,
  "provider": "okta",
  "entityId": "https://example.okta.com/entity",
  "signOnUrl": "https://example.okta.com/sso/saml",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
}
Response (201)
{
  "data": {
    "_id": "sso_001",
    "enabled": true,
    "provider": "okta",
    "entityId": "https://example.okta.com/entity",
    "signOnUrl": "https://example.okta.com/sso/saml",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/sso' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "enabled": true,
    "provider": "okta",
    "entityId": "https://example.okta.com/entity",
    "signOnUrl": "https://example.okta.com/sso/saml",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
  }'
GET /v?/sso

Mengambil konfigurasi SSO saat ini.

Response (200)
{
  "data": {
    "_id": "sso_001",
    "enabled": true,
    "provider": "okta",
    "entityId": "https://example.okta.com/entity",
    "signOnUrl": "https://example.okta.com/sso/saml",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/sso' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/sso

Mengupdate konfigurasi SSO.

Request Body
{
  "enabled": false,
  "provider": "okta",
  "entityId": "https://example.okta.com/entity",
  "signOnUrl": "https://example.okta.com/sso/saml",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
}
Response (200)
{
  "data": {
    "_id": "sso_001",
    "enabled": false,
    "provider": "okta",
    "entityId": "https://example.okta.com/entity",
    "signOnUrl": "https://example.okta.com/sso/saml",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "createdAt": "2026-04-10T10:00:00Z",
    "updatedAt": "2026-04-10T10:05:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/sso' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "enabled": false
  }'
DELETE /v?/sso

Menghapus konfigurasi SSO.

Response (200)
{
  "message": "SSO configuration deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/sso' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Enforced TLS

2 endpoints

Require TLS encryption for all outbound email delivery. Optionally require valid certificates from receiving servers.

GET /v?/enforced-tls

Mengambil konfigurasi enforced TLS.

Response (200)
{
  "data": {
    "requireTls": true,
    "requireValidCert": true
  }
}
PUT /v?/enforced-tls

Mengupdate konfigurasi enforced TLS.

Response (200)
{
  "data": {
    "requireTls": true,
    "requireValidCert": false
  }
}

Scopes

1 endpoint

List all available API permission scopes. Used when creating API keys with restricted access (RBAC).

GET /v?/scopes

Mengambil daftar semua available API scopes (untuk RBAC key management).

Response (200)
{
  "data": [
    "campaigns.read",
    "campaigns.write",
    "contacts.read",
    "contacts.write",
    "webhooks.read",
    "webhooks.write",
    "stats.read",
    "settings.read",
    "settings.write"
  ]
}

Idempotency

4 endpoints

Prevent duplicate operations. Idempotency keys ensure that retrying a request (e.g. after a timeout) does not send the email twice.

GET /v?/idempotency/records/:key

Mengambil detail record idempotency berdasarkan key.

Response (200)
{
  "data": {
    "key": "idem-abc123",
    "status": "completed",
    "messageId": "msg_001",
    "responseCode": 200,
    "createdAt": "2026-04-10T10:00:00Z",
    "expiresAt": "2026-04-11T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/idempotency/records/idem-abc123' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
DELETE /v?/idempotency/records/:key

Menghapus record idempotency berdasarkan key (expire manual).

Response (200)
{
  "message": "Idempotency key expired"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/idempotency/records/idem-abc123' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/idempotency/config

Mengambil konfigurasi idempotency saat ini.

Response (200)
{
  "data": {
    "enabled": true,
    "ttlHours": 24,
    "enforcement": "strict"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/idempotency/config' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/idempotency/config

Mengupdate konfigurasi idempotency.

Request Body
{
  "enabled": true,
  "ttlHours": 48,
  "enforcement": "warn"
}
Response (200)
{
  "data": {
    "enabled": true,
    "ttlHours": 48,
    "enforcement": "warn"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/idempotency/config' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "enabled": true,
    "ttlHours": 48,
    "enforcement": "warn"
  }'

Log Redaction

2 endpoints

Control which email fields (body, subject, headers) are stored in logs. Redact sensitive content for compliance requirements.

GET /v?/log-redaction/config

Mengambil konfigurasi log redaction saat ini.

Response (200)
{
  "data": {
    "enabled": true,
    "redactBody": true,
    "redactSubject": false,
    "redactHeaders": false,
    "allowedFields": ["from", "to", "date"]
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/log-redaction/config' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/log-redaction/config

Mengupdate konfigurasi log redaction.

Request Body
{
  "enabled": true,
  "redactBody": true,
  "redactSubject": true,
  "redactHeaders": false,
  "allowedFields": ["from", "to", "date", "subject"]
}
Response (200)
{
  "data": {
    "enabled": true,
    "redactBody": true,
    "redactSubject": true,
    "redactHeaders": false,
    "allowedFields": ["from", "to", "date", "subject"]
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/log-redaction/config' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "enabled": true,
    "redactBody": true,
    "redactSubject": true,
    "redactHeaders": false,
    "allowedFields": ["from", "to", "date", "subject"]
  }'

Velocity Control

9 endpoints

Automatic anomaly detection on sending patterns. Pauses sending when bounce rates or volume spike unexpectedly to protect your reputation.

GET /v?/velocity/rules

Mengambil semua velocity rules.

Response (200)
{
  "data": [
    {
      "_id": "rule_001",
      "name": "Bounce rate spike",
      "metric": "bounce_rate",
      "threshold": 5.0,
      "action": "pause",
      "cooldownMinutes": 30,
      "active": true,
      "createdAt": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/velocity/rules' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/velocity/rules

Membuat velocity rule baru untuk anomaly detection.

Request Body
{
  "name": "Bounce rate spike",
  "metric": "bounce_rate",
  "threshold": 5.0,
  "action": "pause",
  "cooldownMinutes": 30,
  "active": true
}
Response (201)
{
  "data": {
    "_id": "rule_001",
    "name": "Bounce rate spike",
    "metric": "bounce_rate",
    "threshold": 5.0,
    "action": "pause",
    "cooldownMinutes": 30,
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/velocity/rules' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Bounce rate spike",
    "metric": "bounce_rate",
    "threshold": 5.0,
    "action": "pause",
    "cooldownMinutes": 30,
    "active": true
  }'
GET /v?/velocity/rules/:id

Mengambil detail velocity rule berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "rule_001",
    "name": "Bounce rate spike",
    "metric": "bounce_rate",
    "threshold": 5.0,
    "action": "pause",
    "cooldownMinutes": 30,
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/velocity/rules/rule_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
PUT /v?/velocity/rules/:id

Mengupdate velocity rule berdasarkan ID.

Request Body
{
  "name": "Bounce rate spike (updated)",
  "threshold": 3.0,
  "cooldownMinutes": 60
}
Response (200)
{
  "data": {
    "_id": "rule_001",
    "name": "Bounce rate spike (updated)",
    "metric": "bounce_rate",
    "threshold": 3.0,
    "action": "pause",
    "cooldownMinutes": 60,
    "active": true,
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request PUT 'https://api.mailtarget.co/v1/velocity/rules/rule_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Bounce rate spike (updated)",
    "threshold": 3.0,
    "cooldownMinutes": 60
  }'
DELETE /v?/velocity/rules/:id

Menghapus velocity rule berdasarkan ID.

Response (200)
{
  "message": "Velocity rule deleted"
}
cURL Example 
curl --request DELETE 'https://api.mailtarget.co/v1/velocity/rules/rule_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/velocity/events

Mengambil daftar velocity events (anomaly yang terdeteksi) dengan pagination.

Response (200)
{
  "data": [
    {
      "_id": "evt_001",
      "ruleId": "rule_001",
      "ruleName": "Bounce rate spike",
      "triggeredAt": "2026-04-10T10:30:00Z",
      "action": "pause",
      "metricValue": 7.2,
      "threshold": 5.0,
      "status": "active"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/velocity/events?page=1&perPage=20' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/velocity/events/:id/resolve

Resolve velocity event — menandai anomaly sudah diatasi dan melanjutkan pengiriman.

Response (200)
{
  "message": "Velocity event resolved, sending resumed"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/velocity/events/evt_001/resolve' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
POST /v?/velocity/events/:id/dismiss

Dismiss velocity event — menandai anomaly sebagai false positive.

Response (200)
{
  "message": "Velocity event dismissed"
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/velocity/events/evt_001/dismiss' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/velocity/status

Mengambil status velocity control secara keseluruhan (overview dashboard).

Response (200)
{
  "data": {
    "activeRules": 3,
    "activeEvents": 1,
    "sendingStatus": "throttled",
    "lastChecked": "2026-04-10T10:35:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/velocity/status' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

Data Privacy

3 endpoints

Handle GDPR Right to Be Forgotten (RTBF) and opt-out requests. Permanently delete all data associated with an email address.

POST /v?/data-privacy/rtbf

Membuat Right To Be Forgotten (RTBF) request — menghapus semua data contact.

Request Body
{
  "email": "user@example.com"
}
Response (202)
{
  "data": {
    "_id": "dp_001",
    "type": "rtbf",
    "email": "user@example.com",
    "status": "pending",
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/data-privacy/rtbf' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "user@example.com"
  }'
POST /v?/data-privacy/opt-out

Membuat opt-out request — contact tidak akan menerima email lagi.

Request Body
{
  "email": "user@example.com"
}
Response (202)
{
  "data": {
    "_id": "dp_002",
    "type": "opt_out",
    "email": "user@example.com",
    "status": "pending",
    "createdAt": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request POST 'https://api.mailtarget.co/v1/data-privacy/opt-out' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "user@example.com"
  }'
GET /v?/data-privacy/requests/:id

Mengambil status data privacy request berdasarkan ID.

Response (200)
{
  "data": {
    "_id": "dp_001",
    "type": "rtbf",
    "email": "user@example.com",
    "status": "completed",
    "createdAt": "2026-04-10T10:00:00Z",
    "completedAt": "2026-04-10T10:05:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/data-privacy/requests/dp_001' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'

DMARC Monitoring

9 endpoints

Monitor your domain DMARC/SPF/DKIM status, check blocklist status, detect spam traps, and track overall email health score.

GET /v?/dmarc/domains

Mengambil daftar semua DMARC domains.

Response (200)
{
  "data": [
    {
      "domain": "example.com",
      "dmarcStatus": "pass",
      "lastChecked": "2026-04-10T10:00:00Z"
    }
  ]
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/dmarc/domains' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/dmarc/domains/:domain

Mengambil detail DMARC status untuk domain tertentu.

Response (200)
{
  "data": {
    "domain": "example.com",
    "dmarcStatus": "pass",
    "policy": "reject",
    "spfAligned": true,
    "dkimAligned": true,
    "lastChecked": "2026-04-10T10:00:00Z"
  }
}
cURL Example 
curl --request GET 'https://api.mailtarget.co/v1/dmarc/domains/example.com' \
  --header 'Authorization: Bearer MAILTARGET_API_KEY'
GET /v?/dmarc/domains/:domain/records

Mengambil DMARC DNS records untuk domain.

Response (200)
{
  "data": {
    "domain": "example.com",
    "dmarcRecord": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
    "spfRecord": "v=spf1 include:mailtarget.co -all",
    "dkimSelector": "mt1"
  }
}
GET /v?/dmarc/domains/:domain/setup

Mengambil setup instructions untuk DMARC domain.

Response (200)
{
  "data": {
    "domain": "example.com",
    "steps": [
      { "record": "TXT", "host": "_dmarc.example.com", "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com" }
    ],
    "currentStatus": "not_configured"
  }
}
GET /v?/dmarc/monitored-domains

Mengambil daftar domain yang aktif dimonitor.

Response (200)
{
  "data": [
    {
      "domain": "example.com",
      "monitoringSince": "2026-01-01",
      "status": "active"
    }
  ]
}
GET /v?/dmarc/domains/:domain/blocklists

Mengambil status blocklist untuk domain.

Response (200)
{
  "data": {
    "domain": "example.com",
    "listed": false,
    "blocklists": [],
    "lastChecked": "2026-04-10T10:00:00Z"
  }
}
GET /v?/dmarc/domains/:domain/blocklist-events

Mengambil history blocklist events untuk domain.

Response (200)
{
  "data": [
    {
      "blocklist": "spamhaus.org",
      "listedAt": "2026-03-15T10:00:00Z",
      "delistedAt": "2026-03-16T08:00:00Z",
      "reason": "High complaint rate"
    }
  ]
}
GET /v?/dmarc/spam-traps

Mengambil data spam trap hits.

Response (200)
{
  "data": [
    {
      "email": "trap@spamtrap.example.com",
      "hitCount": 3,
      "lastHit": "2026-04-09T14:00:00Z",
      "source": "purchased_list"
    }
  ]
}
GET /v?/dmarc/health-score

Mengambil email health score keseluruhan.

Response (200)
{
  "data": {
    "score": 87,
    "grade": "B+",
    "factors": {
      "dmarc": 95,
      "spf": 100,
      "dkim": 100,
      "blocklist": 80,
      "spamTraps": 60,
      "bounceRate": 90
    }
  }
}

Data Erasure

2 endpoints

Permanently erase all data associated with an email address. Asynchronous processing with job status tracking.

POST /v?/data-erasure/jobs

Membuat data erasure job — menghapus semua data terkait email address.

Response (202)
{
  "data": {
    "jobId": "de_001",
    "status": "pending",
    "email": "user@example.com"
  }
}
GET /v?/data-erasure/jobs/:id

Mengambil status data erasure job.

Response (200)
{
  "data": {
    "jobId": "de_001",
    "status": "completed"
  }
}

Content Linting

1 endpoint

Analyze email HTML and subject lines for spam triggers, formatting issues, and deliverability risks before sending. Get a deliverability score with actionable fix suggestions.

POST /v?/content/lint

Analisis HTML email dan subject line untuk spam triggers, formatting issues, dan deliverability risks. Returns score (0-100), list of issues dan warnings.

Reputation

7 endpoints

Real-time sender reputation scoring. View overall score, per-domain and per-IP reputation, ISP-specific scores, and actionable recommendations to improve inbox placement.

GET /v?/reputation/score

Mengambil overall sender reputation score beserta breakdown per factor (domain auth, bounce rate, complaint rate, blocklist status, engagement).

GET /v?/reputation/domains

List reputation score semua sending domains. Includes SPF/DKIM/DMARC status, blocklist status, dan ISP-specific scores.

GET /v?/reputation/domains/:domain

Detail reputation untuk satu domain: score, auth status, ISP scores, blocklist.

GET /v?/reputation/ips

List reputation score semua sending IPs. Includes warmup day, ISP scores.

GET /v?/reputation/ips/:ip

Detail reputation untuk satu IP address.

GET /v?/reputation/isp-recommendations

Rekomendasi per ISP (Gmail, Yahoo, Outlook, dll): daily volume limit, current volume, dan action yang disarankan.

GET /v?/reputation/isp-recommendations/:domain

Rekomendasi ISP spesifik untuk satu sending domain.

Send Simulation

2 endpoints

Dry-run email sends without actually delivering. Check per-recipient eligibility, content spam score, policy evaluation, and predict inbox vs spam placement per provider.

POST /v?/messages/simulate

Dry-run send tanpa actually sending. Returns per-recipient eligibility (suppressed? deduped?), content analysis (spam score, HTML validation, broken links), dan policy evaluation (rate limit, quota, velocity, TLS).

POST /v?/messages/predict-inbox

Predict inbox placement per recipient. Returns probability of inbox vs spam per provider (Gmail, Yahoo, Outlook) with contributing factors.

Inbound Classify

2 endpoints

Auto-classify incoming emails: detect category (support, sales, billing), intent, sentiment, language, auto-replies, and out-of-office. Route emails to the right handler automatically.

POST /v?/inbound/classify

Classify satu inbound email. Returns category (support, sales, billing, spam, auto-reply, out-of-office, bounce), intent, sentiment, language, priority, dan suggested labels.

POST /v?/inbound/classify/batch

Classify multiple inbound emails in one call.

Threads

6 endpoints

Group related inbound and outbound emails into conversations. List, label, update status, and reply to threads. Built for AI agents that handle email workflows.

GET /v?/threads

List email threads with pagination. Filter by status (open, closed, pending) and direction (inbound, outbound, both).

GET /v?/threads/:id

Detail satu thread.

GET /v?/threads/:id/messages

List semua messages dalam thread (chronological). Includes inbound dan outbound messages.

PATCH /v?/threads/:id/labels

Update labels pada thread. Body: `{labels: ["support", "urgent"]}`. Useful for AI agent categorization.

PATCH /v?/threads/:id/status

Update thread status. Body: `{status: "closed"}`. Values: open, closed, pending, snoozed.

POST /v?/threads/:id/reply

Reply ke thread — send outbound email as part of existing conversation. Automatically sets correct In-Reply-To dan References headers.