Transactional API

v. 1.0.59

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.
- 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.
  body parameters
  keyrequired
  string
  a valid api key
  addressrequired
  string
  the email address of the sender
  Get sender info
  const mailchimpClient = require("@mailchimp/mailchimp_transactional")( "YOUR_API_KEY" ); const run = async () => { const response = await mailchimpClient.senders.info({ address: "address" }); console.log(response); }; run();
  Success Response
  HTTP Status 200
  the detailed information on the sender
  address
  string
  the sender's email address
  created_at
  string
  the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
  sent
  integer
  the total number of messages sent by this sender
  hard_bounces
  integer
  the total number of hard bounces by messages by this sender
  soft_bounces
  integer
  the total number of soft bounces by messages by this sender
  rejects
  integer
  the total number of rejected messages by this sender
  complaints
  integer
  the total number of spam complaints received for messages by this sender
  unsubs
  integer
  the total number of unsubscribe requests received for messages by this sender
  opens
  integer
  the total number of times messages by this sender have been opened
  clicks
  integer
  the total number of times tracked URLs in messages by this sender have been clicked
  stats
  object
  an aggregate summary of the sender's sending stats
  Show Properties
  Example response
  JSON
  { "address": "user@example.com", "created_at": "2019-08-24T14:15:22Z", "sent": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "complaints": 0, "unsubs": 0, "opens": 0, "clicks": 0, "stats": { "today": { "sent": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "complaints": 0, "unsubs": 0, "opens": 0, "unique_opens": 0, "clicks": 0, "unique_clicks": 0 }, "last_7_days": { "sent": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "complaints": 0, "unsubs": 0, "opens": 0, "unique_opens": 0, "clicks": 0, "unique_clicks": 0 }, "last_30_days": { "sent": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "complaints": 0, "unsubs": 0, "opens": 0, "unique_opens": 0, "clicks": 0, "unique_clicks": 0 }, "last_60_days": { "sent": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "complaints": 0, "unsubs": 0, "opens": 0, "unique_opens": 0, "clicks": 0, "unique_clicks": 0 }, "last_90_days": { "sent": 0, "hard_bounces": 0, "soft_bounces": 0, "rejects": 0, "complaints": 0, "unsubs": 0, "opens": 0, "unique_opens": 0, "clicks": 0, "unique_clicks": 0 } } }
- 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.

Mailchimp Transactional

API Reference

Transactional API

Allowlists

Add email to allowlist

List allowlisted emails

Remove email from allowlist

Exports

View export info

List exports

Export denylist

Export Allowlist

Export Allowlist

Export activity history

IPs

List ip addresses

Get ip info

Request additional ip

Start ip warmup

Cancel ip warmup

Move ip to different pool

Delete ip address

List ip pools

Get ip pool info

Add ip pool

Delete ip pool

Test custom dns

Set custom dns

Inbound

List inbound domains

Add inbound domain

Check domain settings

Delete inbound domain

List mailbox routes

Add mailbox route

Update mailbox route

Delete mailbox route

Send mime document

Messages

Send new message

Send using message template

Search messages by date

Search messages by hour

Get message info

Get message content

Parse mime document

Send mime document

List scheduled emails

Cancel scheduled email

Reschedule email

Metadata

List metadata fields

Add metadata field

Update metadata field

Delete metadata field

Rejects

Add email to denylist

List denylisted emails

Delete email from denylist

Senders

List account senders

List sender domains

Add sender domain

Check domain settings

Verify domain

Get sender info

body parameters

Get sender info

Success Response

HTTP Status 200

Example response

View sender history

Subaccounts

List subaccounts

Add subaccount

Get subaccount info

Update subaccount

Delete subaccount

Pause subaccount

Resume subaccount