Transactional API
Allowlists
Add, list, or delete from your Rejection Allowlist.
Add email to allowlist
post
/allowlists/add
Adds an email to your email rejection allowlist. If the address is currently on your denylist, that denylist entry will be removed automatically.
List allowlisted emails
post
/allowlists/list
Retrieves your email rejection allowlist. You can provide an email address or search prefix to limit the results. Returns up to 1000 results.
Remove email from allowlist
post
/allowlists/delete
Removes an email address from the allowlist.
Exports
Start an export, or get information on export jobs in progress.
View export info
post
/exports/info
Returns information about an export job. If the export job's state is 'complete', the returned data will include a URL you can use to fetch the results. Every export job produces a zip archive, but the format of the archive is distinct for each job type. The api calls that initiate exports include more details about the output format for that job type.
List exports
post
/exports/list
Returns a list of your exports.
Export denylist
post
/exports/rejects
Begins an export of your rejection denylist. The denylist will be exported to a zip archive containing a single file named rejects.csv that includes the following fields: email, reason, detail, created_at, expires_at, last_event_at, expires_at.
Export Allowlist
post
/exports/whitelist
Begins an export of your rejection allowlist. The allowlist will be exported to a zip archive containing a single file named allowlist.csv that includes the following fields: email, detail, created_at.
Export Allowlist
post
/exports/allowlist
Begins an export of your rejection allowlist. The allowlist will be exported to a zip archive containing a single file named allowlist.csv that includes the following fields: email, detail, created_at.
Export activity history
post
/exports/activity
Begins an export of your activity history. The activity will be exported to a zip archive containing a single file named activity.csv in the same format as you would be able to export from your account's activity view. It includes the following fields: Date, Email Address, Sender, Subject, Status, Tags, Opens, Clicks, Bounce Detail. If you have configured any custom metadata fields, they will be included in the exported data.
IPs
Request and manage Dedicated IPs for your account, and set up reverse DNS.
List ip addresses
post
/ips/list
Lists your dedicated IPs.
Get ip info
post
/ips/info
Retrieves information about a single dedicated IP.
Request additional ip
post
/ips/provision
Requests an additional dedicated IP for your account. Accounts may have one outstanding request at any time, and provisioning requests are processed within 24 hours.
Start ip warmup
post
/ips/start-warmup
Begins the warmup process for a dedicated IP. During the warmup process, the Transactional API will gradually increase the percentage of your mail that is sent over the warming-up IP, over a period of roughly 30 days. The rest of your mail will be sent over shared IPs or other dedicated IPs in the same pool.
Cancel ip warmup
post
/ips/cancel-warmup
Cancels the warmup process for a dedicated IP.
Move ip to different pool
post
/ips/set-pool
Moves a dedicated IP to a different pool.
Delete ip address
post
/ips/delete
Deletes a dedicated IP. This is permanent and cannot be undone.
List ip pools
post
/ips/list-pools
Lists your dedicated IP pools.
Get ip pool info
post
/ips/pool-info
Describes a single dedicated IP pool.
Add ip pool
post
/ips/create-pool
Creates a pool and returns it. If a pool already exists with this name, no action will be performed.
Delete ip pool
post
/ips/delete-pool
Deletes a pool. A pool must be empty before you can delete it, and you cannot delete your default pool.
Test custom dns
post
/ips/check-custom-dns
Tests whether a domain name is valid for use as the custom reverse DNS for a dedicated IP.
Set custom dns
post
/ips/set-custom-dns
Configures the custom DNS name for a dedicated IP.
Inbound
Manage your inbound domains and routes.
List inbound domains
post
/inbound/domains
List the domains that have been configured for inbound delivery.
Add inbound domain
post
/inbound/add-domain
Add an inbound domain to your account.
Check domain settings
post
/inbound/check-domain
Check the MX settings for an inbound domain. The domain must have already been added with the add-domain call.
Delete inbound domain
post
/inbound/delete-domain
Delete an inbound domain from the account. All mail will stop routing for this domain immediately.
List mailbox routes
post
/inbound/routes
List the mailbox routes defined for an inbound domain.
Add mailbox route
post
/inbound/add-route
Add a new mailbox route to an inbound domain.
Update mailbox route
post
/inbound/update-route
Update the pattern or webhook of an existing inbound mailbox route. If null is provided for any fields, the values will remain unchanged.
Delete mailbox route
post
/inbound/delete-route
Delete an existing inbound mailbox route.
Send mime document
post
/inbound/send-raw
Take a raw MIME document destined for a domain with inbound domains set up, and send it to the inbound hook exactly as if it had been sent over SMTP.
Messages
Send, schedule, or get information on your emails.
Send new message
post
/messages/send
Send a new transactional message through the Transactional API.
Send using message template
post
/messages/send-template
Send a new transactional message through the Transactional API using a template.
Search messages by date
post
/messages/search
Search recently sent messages and optionally narrow by date range, tags, senders, and API keys. If no date range is specified, results within the last 7 days are returned. This method may be called up to 20 times per minute. If you need the data more often, you can use /messages/info.json to get the information for a single message, or webhooks to push activity to your own application for querying.
Search messages by hour
post
/messages/search-time-series
Search the content of recently sent messages and return the aggregated hourly stats for matching messages.
Get message info
post
/messages/info
Get the information for a single recently sent message.
Get message content
post
/messages/content
Get the full content of a recently sent message.
Parse mime document
post
/messages/parse
Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces.
Send mime document
post
/messages/send-raw
Take a raw MIME document for a message, and send it exactly as if it were sent through the Transactional API's SMTP servers.
List scheduled emails
post
/messages/list-scheduled
Queries your scheduled emails.
Cancel scheduled email
post
/messages/cancel-scheduled
Cancels a scheduled email.
Reschedule email
post
/messages/reschedule
Reschedules a scheduled email.
Metadata
Manage your custom metadata fields in your account.
List metadata fields
post
/metadata/list
Get the list of custom metadata fields indexed for the account.
body parameters
- keyrequiredstring
a valid api key
List metadata fields
const mailchimpClient = require("@mailchimp/mailchimp_transactional")( "YOUR_API_KEY" ); const run = async () => { const response = await mailchimpClient.metadata.list(); console.log(response); }; run();Success Response
HTTP Status 200
the custom metadata fields for the account
- Arrayobject[]
the individual custom metadata field info
Show Properties
Example response
[ { "name": "string", "state": "active", "view_template": "string" } ]Add metadata field
post
/metadata/add
Add a new custom metadata field to be indexed for the account.
Update metadata field
post
/metadata/update
Update an existing custom metadata field.
Delete metadata field
post
/metadata/delete
Delete an existing custom metadata field. Deletion isn't instataneous, and /metadata/list will continue to return the field until the asynchronous deletion process is complete.
Rejects
Add, list, or delete from your Rejection Denylist.
Add email to denylist
post
/rejects/add
Adds an email to your email rejection denylist. Addresses that you add manually will never expire and there is no reputation penalty for removing them from your denylist. Attempting to denylist an address that has been added to the allowlist will have no effect.
List denylisted emails
post
/rejects/list
Retrieves your email rejection denylist. You can provide an email address to limit the results. Returns up to 1000 results. By default, entries that have expired are excluded from the results; set include_expired to true to include them.
Delete email from denylist
post
/rejects/delete
Deletes an email rejection. There is no limit to how many rejections you can remove from your denylist, but keep in mind that each deletion has an affect on your reputation.
Senders
Manage or get information about your sending domains.
List account senders
post
/senders/list
Return the senders that have tried to use this account.
List sender domains
post
/senders/domains
Returns the sender domains that have been added to this account.
Add sender domain
post
/senders/add-domain
Adds a sender domain to your account. Sender domains are added automatically as you send, but you can use this call to add them ahead of time.
Check domain settings
post
/senders/check-domain
Checks the SPF and DKIM settings for a domain, as well the domain verification. If you haven't already added this domain to your account, it will be added automatically.
Verify domain
post
/senders/verify-domain
Sends a verification email in order to verify ownership of a domain. Domain verification is a required step to confirm ownership of a domain. Once a domain has been verified in a Transactional API account, other accounts may not have their messages signed by that domain unless they also verify the domain. This prevents other Transactional API accounts from sending mail signed by your domain.
Get sender info
post
/senders/info
Return more detailed information about a single sender, including aggregates of recent stats.
View sender history
post
/senders/time-series
Return the recent history (hourly stats for the last 30 days) for a sender.
Subaccounts
Manage your subaccounts, including the abilitiy to pause and resume sending.
List subaccounts
post
/subaccounts/list
Get the list of subaccounts defined for the account, optionally filtered by a prefix.
Add subaccount
post
/subaccounts/add
Add a new subaccount.
Get subaccount info
post
/subaccounts/info
Given the ID of an existing subaccount, return the data about it.
Update subaccount
post
/subaccounts/update
Update an existing subaccount.
Delete subaccount
post
/subaccounts/delete
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.
Pause subaccount
post
/subaccounts/pause
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.
Resume subaccount
post
/subaccounts/resume
Resume a paused subaccount's sending.
Tags
List, delete, or get information on your Tags and their sending statistics.
List tags
post
/tags/list
Return all of the user-defined tag information.
Delete tag
post
/tags/delete
Deletes a tag permanently. Deleting a tag removes the tag from any messages that have been sent, and also deletes the tag's stats. There is no way to undo this operation, so use it carefully.
Get tag info
post
/tags/info
Return more detailed information about a single tag, including aggregates of recent stats.
View tag history
post
/tags/time-series
Return the recent history (hourly stats for the last 30 days) for a tag.
View all tags history
post
/tags/all-time-series
Return the recent history (hourly stats for the last 30 days) for all tags.
Templates
Manage the Templates in your account.
Add template
post
/templates/add
Add a new template.
Get template info
post
/templates/info
Get the information for an existing template.
Update template
post
/templates/update
Update the code for an existing template. If null is provided for any fields, the values will remain unchanged.
Publish template content
post
/templates/publish
Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.
Delete template
post
/templates/delete
Delete a template.
List templates
post
/templates/list
Return a list of all the templates available to this user.
Get template history
post
/templates/time-series
Return the recent history (hourly stats for the last 30 days) for a template.
Render html template
post
/templates/render
Inject content and optionally merge fields into a template, returning the HTML that results.
URLs
Manage your tracking domains. Some of these endpoints may be deprecated.
List most clicked urlsdeprecated
post
/urls/list
Get the 100 most clicked URLs.
Search most clicked urlsdeprecated
post
/urls/search
Return the 100 most clicked URLs that match the search query given.
Get url historydeprecated
post
/urls/time-series
Return the recent history (hourly stats for the last 30 days) for a URL
List tracking domains
post
/urls/tracking-domains
Get the list of tracking domains set up for this account.
Add tracking domains
post
/urls/add-tracking-domain
Add a tracking domain to your account.
Check cname settings
post
/urls/check-tracking-domain
Checks the CNAME settings for a tracking domain. The domain must have been added already with the add-tracking-domain call.
Users
Get information about your account, or ping Transactional.
Get user info
post
/users/info
Return the information about the API-connected user.
Ping
post
/users/ping
Validate an API key and respond to a ping.
Ping 2
post
/users/ping2
Validate an API key and respond to a ping (JSON parser version).
List account senders
post
/users/senders
Return the senders that have tried to use this account, both verified and unverified.
Webhooks
Manage the webhooks in your account.
List webhooks
post
/webhooks/list
Get the list of all webhooks defined on the account.
Add webhook
post
/webhooks/add
Add a new webhook.
Get webhook info
post
/webhooks/info
Given the ID of an existing webhook, return the data about it.
Update webhook
post
/webhooks/update
Update an existing webhook.
Delete webhook
post
/webhooks/delete
Delete an existing webhook.
Whitelists
Add, list, or delete from your Rejection Allowlist. These endpoints are being replaced with a series of functionally identical endpoints called /allowlists.
Add email to allowlist
post
/whitelists/add
Adds an email to your email rejection allowlist. If the address is currently on your denylist, that denylist entry will be removed automatically.
List allowlisted emails
post
/whitelists/list
Retrieves your email rejection allowlist. You can provide an email address or search prefix to limit the results. Returns up to 1000 results.
Remove email from allowlist
post
/whitelists/delete
Removes an email address from the allowlist.