Marketing Arsenal Builder

Quick Start

Get started with the MAB API in just a few lines of code. First, grab your API key from the dashboard, then make your first request:

1
Get your API key
Generate an API key from your account dashboard
2
Install an SDK
Choose from Node.js, Python, Ruby, Go, or PHP
3
Make your first request
Test the connection by listing your campaigns

First API Request

cURL

curl -X GET "https://api.marketingarsenal.com/v2/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentication

MAB API uses API keys and OAuth 2.0 for secure authentication. All API requests must be made over HTTPS.

API Key Authentication

Quick and simple authentication for server-side applications

How to Get Your API Key

Log in to your MAB dashboard
Navigate to Settings > API Keys
Click "Generate New API Key"
Copy your key and store it securely (it won't be shown again)
Use the key in the Authorization header of your requests

Using Your API Key

JavaScript

// Using API Key in headers
const response = await fetch('https://api.mab.com/v1/campaigns', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

cURL

curl -X GET "https://api.mab.com/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Security Best Practices

Never expose API keys in client-side code or version control
Use environment variables to store keys securely
Rotate keys regularly and immediately if compromised
Use different keys for development and production environments

OAuth 2.0 Authentication

Recommended for Apps

Secure authentication for third-party applications and user-based access

Authorization Code Flow

User Authorization

Redirect user to MAB's authorization page to grant permissions

Authorization Code

User is redirected back with an authorization code

Token Exchange

Exchange authorization code for access and refresh tokens

API Access

Use access token to make authenticated API requests

Implementation Example

JavaScript

// OAuth 2.0 Authorization Code Flow
// Step 1: Redirect user to authorization URL
const authUrl = `https://api.mab.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=campaigns:read campaigns:write`;

// Step 2: Exchange authorization code for access token
const tokenResponse = await fetch('https://api.mab.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET,
    redirect_uri: YOUR_REDIRECT_URI
  })
});

const { access_token, refresh_token } = await tokenResponse.json();

Refreshing Access Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring the user to re-authenticate.

JavaScript

// Refresh expired access token
const refreshResponse = await fetch('https://api.mab.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: YOUR_REFRESH_TOKEN,
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET
  })
});

const { access_token } = await refreshResponse.json();

OAuth Best Practices

Store refresh tokens securely (e.g., encrypted database)
Implement token refresh before expiration
Request only the scopes your application needs
Handle token revocation gracefully

API Endpoints

Complete reference for all 35 endpoints across 8 categories.

POST

/v1/auth/token

Create Access Token

Generate a new API access token using client credentials

Request Body

Name	Type	Required	Description	Default
`client_id`	`string`	Required	Your application client ID	—
`client_secret`	`string`	Required	Your application client secret	—
`grant_type`	`string`	Required	OAuth grant type	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "mab_client_abc123xyz",
    "client_secret": "mab_secret_def456uvw",
    "grant_type": "client_credentials"
  }'

Response Examples

200Token created successfully

JSON

{
  "access_token": "mab_token_abc123xyz789",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "campaigns:read campaigns:write contacts:read"
}

POST

/v1/auth/token/refresh

Refresh Access Token

Refresh an expired access token using a refresh token

Request Body

Name	Type	Required	Description	Default
`refresh_token`	`string`	Required	Your refresh token	—
`grant_type`	`string`	Required	Must be refresh_token	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "mab_refresh_xyz789abc",
    "grant_type": "refresh_token"
  }'

Response Examples

200Token refreshed successfully

JSON

{
  "access_token": "mab_token_new123xyz",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mab_refresh_new456abc"
}

POST

/v1/auth/token/revoke

Revoke Access Token

Revoke an active access token

Request Body

Name	Type	Required	Description	Default
`token`	`string`	Required	The token to revoke	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/auth/token/revoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "mab_token_abc123xyz789"}'

Response Examples

200Token revoked successfully

JSON

{
  "message": "Token revoked successfully"
}

GET

/v1/campaigns

List All Campaigns

Retrieve a paginated list of all campaigns

Query Parameters

Name	Type	Required	Description	Default
`page`	`number`	Optional	Page number	`1`
`limit`	`number`	Optional	Items per page	`25`
`status`	`string`	Optional	Filter by campaign status	—

Request Examples

cURL

curl -X GET "https://api.marketingarsenalbuildr.com/v1/campaigns?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Campaigns retrieved successfully

JSON

{
  "data": [{"id": "camp_abc123", "name": "Summer Sale 2025", "type": "email", "status": "sent", "created_at": "2025-06-01T10:00:00Z", "sent_count": 15420}],
  "pagination": {"page": 1, "limit": 25, "total": 142, "total_pages": 6}
}

POST

/v1/campaigns

Create Campaign

Create a new marketing campaign

Request Body

Name	Type	Required	Description	Default
`name`	`string`	Required	Campaign name	—
`type`	`string`	Required	Campaign type	—
`audience_id`	`string`	Required	Target audience ID	—
`template_id`	`string`	Optional	Template ID to use	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome Series", "type": "email", "audience_id": "aud_xyz789", "template_id": "tmpl_abc456"}'

Response Examples

201Campaign created successfully

JSON

{"id": "camp_new123", "name": "Welcome Series", "type": "email", "status": "draft", "audience_id": "aud_xyz789", "created_at": "2025-12-13T15:30:00Z"}

GET

/v1/campaigns/:id

Get Campaign

Retrieve detailed information about a specific campaign

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Campaign ID	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/campaigns/camp_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Campaign retrieved successfully

JSON

{"id": "camp_abc123", "name": "Summer Sale 2025", "type": "email", "status": "sent", "subject": "Get 30% Off This Summer", "audience_id": "aud_xyz789", "stats": {"sent": 15420, "delivered": 15102, "opened": 6843, "clicked": 2156}}

PUT

/v1/campaigns/:id

Update Campaign

Update an existing campaign (only draft campaigns)

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Campaign ID	—

Request Body

Name	Type	Required	Description	Default
`name`	`string`	Optional	Campaign name	—
`subject`	`string`	Optional	Email subject line	—

Request Examples

cURL

curl -X PUT https://api.marketingarsenalbuildr.com/v1/campaigns/camp_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Campaign Name"}'

Response Examples

200Campaign updated successfully

JSON

{"id": "camp_abc123", "name": "Updated Campaign Name", "updated_at": "2025-12-13T16:00:00Z"}

POST

/v1/campaigns/:id/send

Send Campaign

Send a campaign immediately or schedule it for later

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Campaign ID	—

Request Body

Name	Type	Required	Description	Default
`scheduled_at`	`string`	Optional	ISO 8601 timestamp for scheduled send	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/campaigns/camp_abc123/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2025-12-15T10:00:00Z"}'

Response Examples

200Campaign scheduled successfully

JSON

{"id": "camp_abc123", "status": "scheduled", "scheduled_at": "2025-12-15T10:00:00Z"}

DELETE

/v1/campaigns/:id

Delete Campaign

Delete a draft campaign (cannot delete sent campaigns)

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Campaign ID	—

Request Examples

cURL

curl -X DELETE https://api.marketingarsenalbuildr.com/v1/campaigns/camp_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

204Campaign deleted successfully

JSON

GET

/v1/contacts

List Contacts

Retrieve a paginated list of all contacts

Query Parameters

Name	Type	Required	Description	Default
`page`	`number`	Optional	Page number	`1`
`limit`	`number`	Optional	Items per page (max 100)	`50`
`email`	`string`	Optional	Filter by email address	—
`tag`	`string`	Optional	Filter by tag	—

Request Examples

cURL

curl -X GET "https://api.marketingarsenalbuildr.com/v1/contacts?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Contacts retrieved successfully

JSON

{"data": [{"id": "cont_abc123", "email": "sarah.johnson@example.com", "first_name": "Sarah", "last_name": "Johnson", "status": "subscribed", "tags": ["customer", "premium"]}], "pagination": {"page": 1, "limit": 50, "total": 8543, "total_pages": 171}}

POST

/v1/contacts

Create Contact

Add a new contact to your database

Request Body

Name	Type	Required	Description	Default
`email`	`string`	Required	Contact email address	—
`first_name`	`string`	Optional	First name	—
`last_name`	`string`	Optional	Last name	—
`tags`	`array`	Optional	Array of tags	—
`custom_fields`	`object`	Optional	Custom field data	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "tags": ["newsletter", "lead"]}'

Response Examples

201Contact created successfully

JSON

{"id": "cont_new456", "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "status": "subscribed", "tags": ["newsletter", "lead"], "created_at": "2025-12-13T16:30:00Z"}

GET

/v1/contacts/:id

Get Contact

Retrieve detailed information about a specific contact

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Contact ID	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/contacts/cont_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Contact retrieved successfully

JSON

{"id": "cont_abc123", "email": "sarah.johnson@example.com", "first_name": "Sarah", "last_name": "Johnson", "phone": "+1-555-0123", "status": "subscribed", "tags": ["customer", "premium"], "custom_fields": {"company": "Tech Corp"}, "engagement": {"emails_sent": 45, "emails_opened": 32, "emails_clicked": 18}}

PUT

/v1/contacts/:id

Update Contact

Update contact information

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Contact ID	—

Request Body

Name	Type	Required	Description	Default
`first_name`	`string`	Optional	First name	—
`last_name`	`string`	Optional	Last name	—
`tags`	`array`	Optional	Array of tags	—

Request Examples

cURL

curl -X PUT https://api.marketingarsenalbuildr.com/v1/contacts/cont_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["customer", "vip"]}'

Response Examples

200Contact updated successfully

JSON

{"id": "cont_abc123", "email": "sarah.johnson@example.com", "tags": ["customer", "vip"], "updated_at": "2025-12-13T16:45:00Z"}

DELETE

/v1/contacts/:id

Delete Contact

Permanently delete a contact

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Contact ID	—

Request Examples

cURL

curl -X DELETE https://api.marketingarsenalbuildr.com/v1/contacts/cont_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

204Contact deleted successfully

JSON

GET

/v1/audiences

List Audiences

Retrieve all audience segments

Query Parameters

Name	Type	Required	Description	Default
`page`	`number`	Optional	Page number	`1`
`limit`	`number`	Optional	Items per page	`25`

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/audiences \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Audiences retrieved successfully

JSON

{"data": [{"id": "aud_abc123", "name": "Active Customers", "description": "Customers who purchased in last 30 days", "contact_count": 3542, "created_at": "2025-11-01T10:00:00Z"}], "pagination": {"page": 1, "limit": 25, "total": 47, "total_pages": 2}}

POST

/v1/audiences

Create Audience

Create a new audience segment

Request Body

Name	Type	Required	Description	Default
`name`	`string`	Required	Audience name	—
`description`	`string`	Optional	Audience description	—
`conditions`	`object`	Required	Segmentation conditions	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/audiences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP Customers", "description": "High-value repeat customers", "conditions": {"tags": ["customer", "vip"], "engagement_score": {"gte": 80}}}'

Response Examples

201Audience created successfully

JSON

{"id": "aud_new789", "name": "VIP Customers", "description": "High-value repeat customers", "contact_count": 0, "created_at": "2025-12-13T17:00:00Z"}

GET

/v1/audiences/:id

Get Audience

Retrieve detailed information about an audience

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Audience ID	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Audience retrieved successfully

JSON

{"id": "aud_abc123", "name": "Active Customers", "description": "Customers who purchased in last 30 days", "contact_count": 3542, "conditions": {"tags": ["customer"], "last_purchase": {"days_ago": {"lte": 30}}}, "created_at": "2025-11-01T10:00:00Z"}

DELETE

/v1/audiences/:id

Delete Audience

Delete an audience segment

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Audience ID	—

Request Examples

cURL

curl -X DELETE https://api.marketingarsenalbuildr.com/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

204Audience deleted successfully

JSON

GET

/v1/analytics/campaigns/:id

Get Campaign Analytics

Retrieve detailed analytics for a specific campaign

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Campaign ID	—

Query Parameters

Name	Type	Required	Description	Default
`start_date`	`string`	Optional	Start date (ISO 8601)	—
`end_date`	`string`	Optional	End date (ISO 8601)	—

Request Examples

cURL

curl -X GET "https://api.marketingarsenalbuildr.com/v1/analytics/campaigns/camp_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Analytics retrieved successfully

JSON

{"campaign_id": "camp_abc123", "metrics": {"sent": 15420, "delivered": 15102, "bounced": 318, "opened": 6843, "clicked": 2156, "unsubscribed": 42}, "rates": {"delivery_rate": 0.9794, "open_rate": 0.4532, "click_rate": 0.1428}}

GET

/v1/analytics/overview

Get Account Overview

Get high-level account metrics and performance

Query Parameters

Name	Type	Required	Description	Default
`period`	`string`	Optional	Time period	`30d`

Request Examples

cURL

curl -X GET "https://api.marketingarsenalbuildr.com/v1/analytics/overview?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Overview retrieved successfully

JSON

{"period": "30d", "total_contacts": 12543, "active_campaigns": 8, "total_sent": 45230, "average_open_rate": 0.42, "average_click_rate": 0.15, "growth": {"contacts": 0.12, "engagement": 0.08}}

GET

/v1/analytics/engagement

Get Engagement Timeline

Get engagement metrics over time

Query Parameters

Name	Type	Required	Description	Default
`start_date`	`string`	Required	Start date (ISO 8601)	—
`end_date`	`string`	Required	End date (ISO 8601)	—
`interval`	`string`	Optional	Data interval	`day`

Request Examples

cURL

curl -X GET "https://api.marketingarsenalbuildr.com/v1/analytics/engagement?start_date=2025-11-01&end_date=2025-12-01&interval=day" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Engagement data retrieved

JSON

{"interval": "day", "data": [{"date": "2025-11-01", "sent": 1200, "opened": 540, "clicked": 180}, {"date": "2025-11-02", "sent": 1350, "opened": 608, "clicked": 203}]}

POST

/v1/analytics/export

Export Analytics

Request an analytics data export

Request Body

Name	Type	Required	Description	Default
`type`	`string`	Required	Export type	—
`format`	`string`	Required	Export format	—
`start_date`	`string`	Required	Start date	—
`end_date`	`string`	Required	End date	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/analytics/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "campaigns", "format": "csv", "start_date": "2025-11-01", "end_date": "2025-12-01"}'

Response Examples

202Export job created

JSON

{"export_id": "exp_abc123", "status": "processing", "estimated_completion": "2025-12-13T17:30:00Z"}

GET

/v1/automations

List Automations

Retrieve all automation workflows

Query Parameters

Name	Type	Required	Description	Default
`status`	`string`	Optional	Filter by status	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/automations \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Automations retrieved

JSON

{"data": [{"id": "auto_abc123", "name": "Welcome Sequence", "status": "active", "trigger": "contact.created", "enrolled": 1245, "completed": 892, "created_at": "2025-10-15T10:00:00Z"}]}

POST

/v1/automations

Create Automation

Create a new automation workflow

Request Body

Name	Type	Required	Description	Default
`name`	`string`	Required	Automation name	—
`trigger`	`string`	Required	Trigger event	—
`steps`	`array`	Required	Workflow steps	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/automations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome Sequence", "trigger": "contact.created", "steps": [{"type": "wait", "duration": "1h"}, {"type": "send_email", "template_id": "tmpl_123"}]}'

Response Examples

201Automation created

JSON

{"id": "auto_new456", "name": "Welcome Sequence", "status": "draft", "created_at": "2025-12-13T17:30:00Z"}

GET

/v1/automations/:id

Get Automation

Retrieve automation details

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Automation ID	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/automations/auto_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Automation retrieved

JSON

{"id": "auto_abc123", "name": "Welcome Sequence", "status": "active", "trigger": "contact.created", "steps": [{"type": "wait", "duration": "1h"}, {"type": "send_email", "template_id": "tmpl_123"}], "stats": {"enrolled": 1245, "active": 42, "completed": 892}}

POST

/v1/automations/:id/activate

Activate Automation

Activate a draft automation

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Automation ID	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/automations/auto_abc123/activate \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Automation activated

JSON

{"id": "auto_abc123", "status": "active", "activated_at": "2025-12-13T17:45:00Z"}

DELETE

/v1/automations/:id

Delete Automation

Delete an automation workflow

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Automation ID	—

Request Examples

cURL

curl -X DELETE https://api.marketingarsenalbuildr.com/v1/automations/auto_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

204Automation deleted

JSON

GET

/v1/templates

List Templates

Retrieve all templates

Query Parameters

Name	Type	Required	Description	Default
`type`	`string`	Optional	Filter by type	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Templates retrieved

JSON

{"data": [{"id": "tmpl_abc123", "name": "Newsletter Template", "type": "email", "subject": "Monthly Updates", "created_at": "2025-10-01T10:00:00Z"}]}

POST

/v1/templates

Create Template

Create a new template

Request Body

Name	Type	Required	Description	Default
`name`	`string`	Required	Template name	—
`type`	`string`	Required	Template type	—
`subject`	`string`	Optional	Email subject (email only)	—
`content`	`string`	Required	Template content	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome Email", "type": "email", "subject": "Welcome to MAB!", "content": "<h1>Welcome!</h1><p>Thanks for joining.</p>"}'

Response Examples

201Template created

JSON

{"id": "tmpl_new789", "name": "Welcome Email", "type": "email", "created_at": "2025-12-13T18:00:00Z"}

GET

/v1/templates/:id

Get Template

Retrieve template details

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Template ID	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Template retrieved

JSON

{"id": "tmpl_abc123", "name": "Newsletter Template", "type": "email", "subject": "Monthly Updates", "content": "<h1>Updates</h1><p>Here are the latest news...</p>", "created_at": "2025-10-01T10:00:00Z"}

DELETE

/v1/templates/:id

Delete Template

Delete a template

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Template ID	—

Request Examples

cURL

curl -X DELETE https://api.marketingarsenalbuildr.com/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

204Template deleted

JSON

GET

/v1/webhooks

List Webhooks

Retrieve all registered webhooks

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Webhooks retrieved

JSON

{"data": [{"id": "hook_abc123", "url": "https://example.com/webhook", "events": ["campaign.sent", "contact.created"], "active": true, "created_at": "2025-11-01T10:00:00Z"}]}

POST

/v1/webhooks

Create Webhook

Request Body

Name	Type	Required	Description	Default
`url`	`string`	Required	Webhook URL (must be HTTPS)	—
`events`	`array`	Required	Array of event types to subscribe to	—
`secret`	`string`	Optional	Secret for signature verification	—

Request Examples

cURL

curl -X POST https://api.marketingarsenalbuildr.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["campaign.sent", "contact.created"]}'

Response Examples

201Webhook created

JSON

{"id": "hook_new456", "url": "https://example.com/webhook", "events": ["campaign.sent", "contact.created"], "secret": "whsec_abc123xyz789", "active": true, "created_at": "2025-12-13T18:30:00Z"}

GET

/v1/webhooks/:id

Get Webhook

Retrieve webhook details

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Webhook ID	—

Request Examples

cURL

curl -X GET https://api.marketingarsenalbuildr.com/v1/webhooks/hook_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

200Webhook retrieved

JSON

{"id": "hook_abc123", "url": "https://example.com/webhook", "events": ["campaign.sent", "contact.created"], "active": true, "stats": {"total_deliveries": 1542, "failed_deliveries": 8, "last_delivery": "2025-12-13T17:45:00Z"}, "created_at": "2025-11-01T10:00:00Z"}

DELETE

/v1/webhooks/:id

Delete Webhook

Delete a webhook

Path Parameters

Name	Type	Required	Description	Default
`id`	`string`	Required	Webhook ID	—

Request Examples

cURL

curl -X DELETE https://api.marketingarsenalbuildr.com/v1/webhooks/hook_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

204Webhook deleted

JSON

Webhooks

Receive real-time notifications when events occur in your MAB account. Webhooks are delivered as HTTP POST requests to your configured endpoint.

Available Events

Campaign Events

campaign.created

Triggered when a new campaign is created

campaign.updated

Triggered when a campaign is updated

campaign.completed

Triggered when a campaign completes execution

Audience Events

audience.created

Triggered when a new audience segment is created

audience.updated

Triggered when an audience segment is updated

Analytics Events

analytics.report_ready

Triggered when an analytics report is ready for download

Billing Events

billing.payment_succeeded

Triggered when a payment is successfully processed

billing.payment_failed

Triggered when a payment fails

Event Payload Structure

All webhook events follow a consistent payload structure with the event type, timestamp, and event-specific data.

JSON

1 {
2   "event": "campaign.completed",
3   "timestamp": "2024-12-13T10:30:00Z",
4   "data": {
5     "id": "camp_abc123",
6     "name": "Holiday Promotion",
7     "status": "completed",
8     "results": {
9       "sent": 10000,
10       "delivered": 9850,
11       "opened": 4200,
12       "clicked": 1250
13     }
14   },
15   "webhook_id": "wh_xyz789"
16 }

Signature Verification

Required

Verify webhook authenticity using HMAC SHA-256 signatures

Each webhook request includes an x-mab-signature header. Verify this signature to ensure the webhook originated from MAB.

JavaScript

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  const expectedSignature = `sha256=${digest}`;

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js example
app.post('/webhooks/mab', (req, res) => {
  const signature = req.headers['x-mab-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook event
  const { event, data } = req.body;

  // Respond quickly (process async if needed)
  res.status(200).send('Webhook received');

  // Handle event asynchronously
  handleWebhookEvent(event, data);
});

Retry Policy & Best Practices

Automatic Retries

Failed webhooks (non-2xx responses) are retried with exponential backoff: 5s, 25s, 2m, 10m, 1h.

Best Practices

Respond with 2xx status code quickly (within 5 seconds)
Process webhooks asynchronously using background jobs
Always verify the webhook signature before processing
Implement idempotency using webhook_id to handle duplicates
Store webhook events for audit and debugging purposes

Error Codes

MAB API uses standard HTTP status codes to indicate success or failure of requests. All error responses include a JSON body with additional details.

HTTP Status Codes

Code	Name	Description	Troubleshooting
400	Bad Request	The request was invalid or cannot be processed.	Check your request payload for syntax errors or missing required fields.
401	Unauthorized	Authentication credentials are missing or invalid.	Verify your API key is correct and included in the Authorization header.
403	Forbidden	You do not have permission to access this resource.	Check your API key permissions and ensure your plan includes this feature.
404	Not Found	The requested resource does not exist.	Verify the resource ID and endpoint URL are correct.
409	Conflict	The request conflicts with the current state of the resource.	Check for duplicate resources or conflicting operations.
422	Unprocessable Entity	The request was well-formed but contains semantic errors.	Review validation errors in the response and fix invalid data.
429	Too Many Requests	Rate limit exceeded.	Reduce request frequency or upgrade your plan for higher rate limits.
500	Internal Server Error	An unexpected error occurred on the server.	Retry your request. If the issue persists, contact support.
502	Bad Gateway	The server received an invalid response from an upstream server.	Retry your request after a brief delay.
503	Service Unavailable	The service is temporarily unavailable.	Wait and retry. Check status.mab.com for service updates.

Rate Limits

Rate limits protect the API from abuse and ensure fair usage across all clients. Limits vary by plan tier and apply per API key.

Rate Limit Tiers

Tier	Requests/Minute	Requests/Hour	Burst Limit	Features
Free	10	100	15	Basic endpointsRead operations
Pro	100	5,000	150	All endpointsWebhooksPriority support
Enterprise	1,000	50,000	1,500	All endpointsWebhooksCustom rate limitsDedicated support

Rate Limit Headers

Every API response includes headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After (on 429 responses).

JSON

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702468800
Retry-After: 60

Handling Rate Limit Errors

When you exceed the rate limit, the API returns a 429 status code. Implement exponential backoff to handle these errors gracefully.

JavaScript

// Handle rate limit with exponential backoff
async function makeApiRequest(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);

    // Check rate limit headers
    const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const reset = parseInt(response.headers.get('X-RateLimit-Reset'));

    // Log rate limit info
    console.log(`Rate limit: ${remaining}/${limit} remaining`);

    if (response.status === 429) {
      if (retries === 0) {
        throw new Error('Rate limit exceeded, max retries reached');
      }

      // Get retry delay from header or calculate exponential backoff
      const retryAfter = parseInt(response.headers.get('Retry-After')) || 60;
      const delay = retryAfter * 1000;

      console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);

      // Wait and retry
      await new Promise(resolve => setTimeout(resolve, delay));
      return makeApiRequest(url, options, retries - 1);
    }

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Best Practices

Implement request queuing to automatically manage rate limits
Cache API responses to reduce redundant requests
Use batch endpoints when available to group multiple operations
Monitor rate limit headers and adjust request frequency proactively
Consider upgrading your plan if you consistently hit rate limits

SDKs & Libraries

Official client libraries to integrate MAB into your application. All SDKs are open-source and actively maintained.

Node.js

v2.4.0

Official JavaScript/TypeScript SDK for Node.js applications

Installation

JavaScript

npm install @mab/sdk-node
# or
yarn add @mab/sdk-node

Quick Start

JavaScript

import { MAB } from '@mab/sdk-node';

const mab = new MAB({
  apiKey: process.env.MAB_API_KEY,
});

// Create a campaign
const campaign = await mab.campaigns.create({
  name: 'Holiday Promotion',
  channels: ['email', 'sms'],
  audience: { segment: 'engaged_users' },
});

console.log('Campaign created:', campaign.id);

Python

v1.8.2

Official Python SDK for backend applications and data science

Installation

Python

pip install mab-sdk

Quick Start

Python

from mab import MAB

mab = MAB(api_key=os.environ['MAB_API_KEY'])

# Create a campaign
campaign = mab.campaigns.create(
    name='Holiday Promotion',
    channels=['email', 'sms'],
    audience={'segment': 'engaged_users'}
)

print(f'Campaign created: {campaign.id}')

Ruby

v1.5.1

Official Ruby SDK for Rails and Ruby applications

Installation

Ruby

gem install mab-sdk
# or add to Gemfile
gem "mab-sdk"

Quick Start

Ruby

require 'mab'

mab = MAB::Client.new(api_key: ENV['MAB_API_KEY'])

# Create a campaign
campaign = mab.campaigns.create(
  name: 'Holiday Promotion',
  channels: ['email', 'sms'],
  audience: { segment: 'engaged_users' }
)

puts "Campaign created: #{campaign.id}"

Go

v0.12.0

Official Go SDK for high-performance applications

Installation

go get github.com/mab/mab-go

Quick Start

package main

import (
    "context"
    "fmt"
    "os"
    "github.com/mab/mab-go"
)

func main() {
    client := mab.NewClient(os.Getenv("MAB_API_KEY"))

    // Create a campaign
    campaign, err := client.Campaigns.Create(context.Background(), &mab.CampaignCreateParams{
        Name: "Holiday Promotion",
        Channels: []string{"email", "sms"},
        Audience: mab.Audience{Segment: "engaged_users"},
    })

    if err != nil {
        panic(err)
    }

    fmt.Printf("Campaign created: %s\n", campaign.ID)
}

PHP

v3.2.1

Official PHP SDK for Laravel and PHP applications

Installation

PHP

composer require mab/sdk-php

Quick Start

PHP

<?php

require_once 'vendor/autoload.php';

use MAB\Client;

$mab = new Client(getenv('MAB_API_KEY'));

// Create a campaign
$campaign = $mab->campaigns->create([
    'name' => 'Holiday Promotion',
    'channels' => ['email', 'sms'],
    'audience' => ['segment' => 'engaged_users']
]);

echo "Campaign created: " . $campaign->id . "\n";

Ready to Start Building?

Get your API key and start integrating with Marketing Arsenal today

1	{
2	"event": "campaign.completed",
3	"timestamp": "2024-12-13T10:30:00Z",
4	"data": {
5	"id": "camp_abc123",
6	"name": "Holiday Promotion",
7	"status": "completed",
8	"results": {
9	"sent": 10000,
10	"delivered": 9850,
11	"opened": 4200,
12	"clicked": 1250
13	}
14	},
15	"webhook_id": "wh_xyz789"
16	}

API Reference

RESTful API

Secure by Default

Real-time Webhooks

99.99% Uptime

Quick Start

Get your API key

Install an SDK

Make your first request

Authentication

API Key Authentication

How to Get Your API Key

Using Your API Key

OAuth 2.0 Authentication

Authorization Code Flow

Implementation Example

Refreshing Access Tokens

API Endpoints

Authentication

Request Body

Request Examples

Response Examples

Request Body

Request Examples

Response Examples

Request Body

Request Examples

Response Examples

Campaigns

Query Parameters

Request Examples

Response Examples

Request Body

Request Examples

Response Examples

Path Parameters

Request Examples

Response Examples

Path Parameters

Request Body

Request Examples

Response Examples

Path Parameters

Request Body

Request Examples

Response Examples

Path Parameters

Request Examples

Response Examples

Contacts

Query Parameters

Request Examples

Response Examples

Request Body

Request Examples

Response Examples

Path Parameters

Request Examples

Response Examples

Path Parameters

Request Body

Request Examples

Response Examples

Path Parameters

Request Examples

Response Examples

Audiences

Query Parameters

Request Examples

Response Examples

Request Body

Request Examples

Response Examples

Path Parameters

Request Examples

Response Examples

Path Parameters

Request Examples

Response Examples

Analytics