Everything you need to integrate MailJunky into your application.
Install the official SDK for your language:
npm install @mailjunky/sdk
# or
pnpm add @mailjunky/sdk
# or
yarn add @mailjunky/sdkimport { MailJunky } from '@mailjunky/sdk'
const client = new MailJunky({
apiKey: 'mj_live_your_api_key'
})await client.emails.send({
from: 'hello@yourapp.com',
to: 'user@example.com',
subject: 'Welcome!',
html: '<h1>Welcome aboard!</h1>'
})await client.emails.send({
from: 'hello@yourapp.com',
to: ['user1@example.com', 'user2@example.com'],
cc: 'manager@example.com',
bcc: ['analytics@yourapp.com'],
subject: 'Team Update',
html: '<p>Important announcement...</p>'
})Send personalized emails to multiple recipients efficiently:
await client.emails.sendBatch([
{
from: 'hello@yourapp.com',
to: 'user1@example.com',
subject: 'Welcome, John!',
html: '<h1>Hi John, welcome aboard!</h1>'
},
{
from: 'hello@yourapp.com',
to: 'user2@example.com',
subject: 'Welcome, Sarah!',
html: '<h1>Hi Sarah, welcome aboard!</h1>'
}
]){
"id": "email_abc123",
"message_id": "<timestamp.random@yourdomain.com>",
"status": "sent"
}Store and manage your recipient list with custom properties for personalization in emails and workflows.
The upsert endpoint creates a new contact or updates an existing one if the email already exists:
await client.contacts.upsert({
email: 'user@example.com',
first_name: 'John',
last_name: 'Doe',
phone: '+1 555 123 4567',
properties: {
company: 'Acme Inc',
plan: 'pro',
signup_source: 'website'
},
tags: ['customer', 'newsletter']
})Retrieve contacts with optional filtering:
const { data, pagination } = await client.contacts.list({
page: 1,
limit: 25,
status: 'active',
tag: 'customer'
})
// data contains array of contacts
// pagination: { page, limit, total, has_more }await client.contacts.update('contact_id', {
tags: ['customer', 'vip'],
properties: { plan: 'enterprise' },
status: 'active' // or 'unsubscribed'
})Import up to 1,000 contacts at once:
const result = await client.contacts.batch({
contacts: [
{ email: 'user1@example.com', first_name: 'User', last_name: 'One' },
{ email: 'user2@example.com', first_name: 'User', last_name: 'Two' },
// ... up to 1000 contacts
]
})
// result: { created: 150, updated: 50, failed: [] }Contact properties can be used as variables in your email templates:
In your email template HTML:
Hi {{contact.first_name}},<br>
Your {{contact.properties.plan}} plan is active. Track user behavior to trigger smart email workflows.
Event tracking is a premium feature with strict volume limits to ensure platform stability and cost control. Events are charged based on your plan tier and monthly volume.
await client.events.track({
event: 'product_viewed',
user: 'user@example.com',
properties: {
product_id: 'prod_123',
price: 49.99
}
})user_signed_upNew user registrationpage_viewUser viewed a pagecart_addedItem added to cartcheckout_completedPurchase completedCreate automated email sequences triggered by user behavior.
Describe your workflow in plain English and our AI will build it for you!
Event-triggered workflows consume event quota each time they're triggered. High-volume workflows can quickly use your monthly event allocation.
Example: A "cart_abandoned" workflow triggered 100,000 times/month = 100k events consumed. On the Free plan (10k events), this would hit your limit in 3 days. Consider upgrading to Pro (500k events) for high-traffic workflows.
Send a reminder email 30 minutes after cart addition if no checkout occurs.
{
"name": "Cart Abandonment - 30min",
"trigger_type": "EVENT",
"trigger_config": {
"eventName": "cart_added",
"delay": 30
},
"conditions": [
{
"type": "event_not_occurred",
"event": "checkout_completed",
"within_minutes": 30
}
],
"actions": [
{
"type": "send_email",
"config": {
"from": "hello@yourapp.com",
"subject": "You left something in your cart!",
"template": "cart_reminder"
}
}
]
}All requests must include your API key:
Authorization: Bearer mj_live_your_api_key_here| Permission | Description |
|---|---|
send | Send emails |
track | Track user events |
contacts | Manage contacts (create, update, delete) |
read | Read analytics, logs, and contacts |
* | All permissions |
API requests are rate limited based on your plan tier and endpoint type:
| Plan | Emails/Hour | Emails/Month |
|---|---|---|
| Free | 100 emails/hour | 1,000 emails |
| Pro | 1,000 emails/hour | 50,000 emails |
| Enterprise | Custom | Unlimited |
⚠️ Cost Warning: Event tracking consumes significant server resources. We enforce strict limits to prevent runaway costs.
When you exceed your monthly event quota, additional events are charged at $0.10 per 1,000 events. Exceeding hourly rate limits will result in 429 errors until the limit resets.
| Plan | Events/Hour | Included/Month | Overage Cost |
|---|---|---|---|
| Free | 1,000/hour | 10,000 events | Hard limit |
| Pro | 10,000/hour | 500,000 events | $0.10/1k events |
| Enterprise | Custom | Custom volume | Negotiated |
Every API response includes rate limit information:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640995200When you exceed the rate limit, you'll receive a 429 status code:
try {
await client.emails.send({ /* ... */ })
} catch (error) {
if (error.status === 429) {
// Rate limit exceeded
const retryAfter = error.headers['retry-after']
console.log(\`Rate limited. Retry after \${retryAfter} seconds\`)
}
}Start sending emails and building AI-powered workflows today.