nodejs

Choose Language

Subaccounts Calls

/subaccounts/list.json

Get the list of subaccounts defined for the account, optionally filtered by a prefix

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var q = "cust-1"; mandrill_client.subaccounts.list({"q": q}, function(result) { console.log(result); /* [{ "id": "cust-123", "name": "ABC Widgets, Inc.", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42 }] */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Invalid_Key - Invalid API key });
Parameters
q string an optional prefix to filter the subaccounts' ids and names
Return Value
array the subaccounts for the account, up to a maximum of 1,000
return[] struct the individual subaccount info
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/subaccounts/add.json

Add a new subaccount

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var id = "cust-123"; var name = "ABC Widgets, Inc."; var notes = "Free plan user, signed up on 2013-01-01 12:00:00"; var custom_quota = 42; mandrill_client.subaccounts.add({"id": id, "name": name, "notes": notes, "custom_quota": custom_quota}, function(result) { console.log(result); /* { "id": "cust-123", "name": "ABC Widgets, Inc.", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42 } */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Invalid_Key - Invalid API key });
Parameters
id* string a unique identifier for the subaccount to be used in sending calls
Validation: required, maxlength(255)
name string an optional display name to further identify the subaccount
Validation: maxlength(1024)
notes string optional extra text to associate with the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, Mandrill will manage this based on reputation
Validation: greaterthan(0)
Return Value
struct the information saved about the new subaccount
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/subaccounts/info.json

Given the ID of an existing subaccount, return the data about it

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var id = "cust-123"; mandrill_client.subaccounts.info({"id": id}, function(result) { console.log(result); /* { "id": "cust-123", "name": "ABC Widgets, Inc.", "notes": "Free plan user, signed up on 2013-01-01 12:00:00", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42, "sent_hourly": 42, "hourly_quota": 42, "last_30_days": { "sent": 42, "hard_bounces": 42, "soft_bounces": 42, "rejects": 42, "complaints": 42, "unsubs": 42, "opens": 42, "unique_opens": 42, "clicks": 42, "unique_clicks": 42 } } */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Unknown_Subaccount - No subaccount exists with the id 'customer-123' });
Parameters
id* string the unique identifier of the subaccount to query
Validation: required
Return Value
struct the information about the subaccount
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
notes string optional extra text to associate with the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
sent_hourly integer the number of emails the subaccount has sent in the last hour
hourly_quota integer the current hourly quota for the subaccount, either manual or reputation-based
last_30_days struct stats for this subaccount in the last 30 days
sent integer the number of emails sent for this subaccount in the last 30 days
hard_bounces integer the number of emails hard bounced for this subaccount in the last 30 days
soft_bounces integer the number of emails soft bounced for this subaccount in the last 30 days
rejects integer the number of emails rejected for sending this subaccount in the last 30 days
complaints integer the number of spam complaints for this subaccount in the last 30 days
unsubs integer the number of unsbuscribes for this subaccount in the last 30 days
opens integer the number of times emails have been opened for this subaccount in the last 30 days
unique_opens integer the number of unique opens for emails sent for this subaccount in the last 30 days
clicks integer the number of URLs that have been clicked for this subaccount in the last 30 days
unique_clicks integer the number of unique clicks for emails sent for this subaccount in the last 30 days
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/subaccounts/update.json

Update an existing subaccount

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var id = "cust-123"; var name = "ABC Widgets, Inc."; var notes = "Free plan user, signed up on 2013-01-01 12:00:00"; var custom_quota = 42; mandrill_client.subaccounts.update({"id": id, "name": name, "notes": notes, "custom_quota": custom_quota}, function(result) { console.log(result); /* { "id": "cust-123", "name": "ABC Widgets, Inc.", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42 } */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Unknown_Subaccount - No subaccount exists with the id 'customer-123' });
Parameters
id* string the unique identifier of the subaccount to update
Validation: required
name string an optional display name to further identify the subaccount
Validation: maxlength(1024)
notes string optional extra text to associate with the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, Mandrill will manage this based on reputation
Validation: greaterthan(0)
Return Value
struct the information for the updated subaccount
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/subaccounts/delete.json

Delete an existing subaccount. Any email related to the subaccount will be saved, but stats will be removed and any future sending calls to this subaccount will fail.

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var id = "cust-123"; mandrill_client.subaccounts.delete({"id": id}, function(result) { console.log(result); /* { "id": "cust-123", "name": "ABC Widgets, Inc.", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42 } */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Unknown_Subaccount - No subaccount exists with the id 'customer-123' });
Parameters
id* string the unique identifier of the subaccount to delete
Validation: required
Return Value
struct the information for the deleted subaccount
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/subaccounts/pause.json

Pause a subaccount's sending. Any future emails delivered to this subaccount will be queued for a maximum of 3 days until the subaccount is resumed.

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var id = "cust-123"; mandrill_client.subaccounts.pause({"id": id}, function(result) { console.log(result); /* { "id": "cust-123", "name": "ABC Widgets, Inc.", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42 } */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Unknown_Subaccount - No subaccount exists with the id 'customer-123' });
Parameters
id* string the unique identifier of the subaccount to pause
Validation: required
Return Value
struct the information for the paused subaccount
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/subaccounts/resume.json

Resume a paused subaccount's sending

Example Call

mandrill_client = new mandrill.Mandrill('YOUR_API_KEY'); var id = "cust-123"; mandrill_client.subaccounts.resume({"id": id}, function(result) { console.log(result); /* { "id": "cust-123", "name": "ABC Widgets, Inc.", "custom_quota": 42, "status": "active", "reputation": 42, "created_at": "2013-01-01 15:30:27", "first_sent_at": "2013-01-01 15:30:29", "sent_weekly": 42, "sent_monthly": 42, "sent_total": 42 } */ }, function(e) { // Mandrill returns the error as an object with name and message keys console.log('A mandrill error occurred: ' + e.name + ' - ' + e.message); // A mandrill error occurred: Unknown_Subaccount - No subaccount exists with the id 'customer-123' });
Parameters
id* string the unique identifier of the subaccount to resume
Validation: required
Return Value
struct the information for the resumed subaccount
id string a unique indentifier for the subaccount
name string an optional display name for the subaccount
custom_quota integer an optional manual hourly quota for the subaccount. If not specified, the hourly quota will be managed based on reputation
status string the current sending status of the subaccount, one of "active" or "paused"
reputation integer the subaccount's current reputation on a scale from 0 to 100
created_at string the date and time that the subaccount was created as a UTC string in YYYY-MM-DD HH:MM:SS format
first_sent_at string the date and time that the subaccount first sent as a UTC string in YYYY-MM-DD HH:MM:SS format
sent_weekly integer the number of emails the subaccount has sent so far this week (weeks start on midnight Monday, UTC)
sent_monthly integer the number of emails the subaccount has sent so far this month (months start on midnight of the 1st, UTC)
sent_total integer the number of emails the subaccount has sent since it was created
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
Unknown_Subaccount The provided subaccount id does not exist.
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.