python

Choose Language

Mandrill API Documentation - Python

Requirements

  • Python 2.6+, Python 3.0+

Getting the Library

The preferred method of installing the Mandrill Python API client is by using pip. If you do not already have pip installed, the easiest method is to use the stand-alone pip installer.

If you're using Linux, Mac OS X, or another flavor of unix, you can use the command sudo pip install mandrill in a shell prompt. If you use Windows, start a command shell with administrator privileges and use the command pip install mandrill to install Mandrill to your system.

If you're using a virtualenv to manage your project, you do not need to use sudo or administrator privileges.

Using the Library

Now that you have a copy of the library in your project, you're ready to start using it. All uses of the Mandrill API start by importing the library module and instantiating the Mandrill class.

import mandrill mandrill_client = mandrill.Mandrill('YOUR_API_KEY')

After that, you're ready to start making calls.

Questions? Problems?

Have you run into difficulties or a method just doesn't seem to work right? Check out our API Support options and we'll be happy to assist you.

API Call Categories

Users Calls

  • info(string key)
    Return the information about the API-connected user
  • ping(string key)
    Validate an API key and respond to a ping
  • ping2(string key)
    Validate an API key and respond to a ping (anal JSON parser version)
  • senders(string key)
    Return the senders that have tried to use this account, both verified and unverified

Messages Calls

  • send(string key, struct message, boolean async, string ip_pool, string send_at)
    Send a new transactional message through Mandrill
  • send-template(string key, string template_name, array template_content, struct message, boolean async, string ip_pool, string send_at)
    Send a new transactional message through Mandrill using a template
  • search(string key, string query, string date_from, string date_to, array tags, array senders, array api_keys, integer limit)
    Search the content of recently sent messages and optionally narrow by date range, tags and senders. 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-time-series(string key, string query, string date_from, string date_to, array tags, array senders)
    Search the content of recently sent messages and return the aggregated hourly stats for matching messages
  • info(string key, string id)
    Get the information for a single recently sent message
  • content(string key, string id)
    Get the full content of a recently sent message
  • parse(string key, string raw_message)
    Parse the full MIME document for an email message, returning the content of the message broken into its constituent pieces
  • send-raw(string key, string raw_message, string|null from_email, string|null from_name, array|null to, boolean async, string ip_pool, string send_at, string return_path_domain)
    Take a raw MIME document for a message, and send it exactly as if it were sent through Mandrill's SMTP servers
  • list-scheduled(string key, string to)
    Queries your scheduled emails by sender or recipient, or both.
  • cancel-scheduled(string key, string id)
    Cancels a scheduled email.
  • reschedule(string key, string id, string send_at)
    Reschedules a scheduled email.

Tags Calls

  • list(string key)
    Return all of the user-defined tag information
  • delete(string key, string tag)
    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.
  • info(string key, string tag)
    Return more detailed information about a single tag, including aggregates of recent stats
  • time-series(string key, string tag)
    Return the recent history (hourly stats for the last 30 days) for a tag
  • all-time-series(string key)
    Return the recent history (hourly stats for the last 30 days) for all tags

Rejects Calls

  • add(string key, string email, string comment, string subaccount)
    Adds an email to your email rejection blacklist. Addresses that you add manually will never expire and there is no reputation penalty for removing them from your blacklist. Attempting to blacklist an address that has been whitelisted will have no effect.
  • list(string key, string email, boolean include_expired, string subaccount)
    Retrieves your email rejection blacklist. 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(string key, string email, string subaccount)
    Deletes an email rejection. There is no limit to how many rejections you can remove from your blacklist, but keep in mind that each deletion has an affect on your reputation.

Whitelists Calls

  • add(string key, string email)
    Adds an email to your email rejection whitelist. If the address is currently on your blacklist, that blacklist entry will be removed automatically.
  • list(string key, string email)
    Retrieves your email rejection whitelist. You can provide an email address or search prefix to limit the results. Returns up to 1000 results.
  • delete(string key, string email)
    Removes an email address from the whitelist.

Senders Calls

  • list(string key)
    Return the senders that have tried to use this account.
  • domains(string key)
    Returns the sender domains that have been added to this account.
  • add-domain(string key, string 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(string key, string domain)
    Checks the SPF and DKIM settings for a domain. If you haven't already added this domain to your account, it will be added automatically.
  • verify-domain(string key, string domain, string mailbox)
    Sends a verification email in order to verify ownership of a domain. Domain verification is an optional step to confirm ownership of a domain. Once a domain has been verified in a Mandrill account, other accounts may not have their messages signed by that domain unless they also verify the domain. This prevents other Mandrill accounts from sending mail signed by your domain.
  • info(string key, string address)
    Return more detailed information about a single sender, including aggregates of recent stats
  • time-series(string key, string address)
    Return the recent history (hourly stats for the last 30 days) for a sender

Urls Calls

  • list(string key)
    Get the 100 most clicked URLs
  • search(string key, string q)
    Return the 100 most clicked URLs that match the search query given
  • time-series(string key, string url)
    Return the recent history (hourly stats for the last 30 days) for a url
  • tracking-domains(string key)
    Get the list of tracking domains set up for this account
  • add-tracking-domain(string key, string domain)
    Add a tracking domain to your account
  • check-tracking-domain(string key, string domain)
    Checks the CNAME settings for a tracking domain. The domain must have been added already with the add-tracking-domain call

Templates Calls

  • add(string key, string name, string from_email, string from_name, string subject, string code, string text, boolean publish, array labels)
    Add a new template
  • info(string key, string name)
    Get the information for an existing template
  • update(string key, string name, string from_email, string from_name, string subject, string code, string text, boolean publish, array labels)
    Update the code for an existing template. If null is provided for any fields, the values will remain unchanged.
  • publish(string key, string name)
    Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.
  • delete(string key, string name)
    Delete a template
  • list(string key, string label)
    Return a list of all the templates available to this user
  • time-series(string key, string name)
    Return the recent history (hourly stats for the last 30 days) for a template
  • render(string key, string template_name, array template_content, array merge_vars)
    Inject content and optionally merge fields into a template, returning the HTML that results

Webhooks Calls

  • list(string key)
    Get the list of all webhooks defined on the account
  • add(string key, string url, string description, array events)
    Add a new webhook
  • info(string key, integer id)
    Given the ID of an existing webhook, return the data about it
  • update(string key, integer id, string url, string description, array events)
    Update an existing webhook
  • delete(string key, integer id)
    Delete an existing webhook

Subaccounts Calls

  • list(string key, string q)
    Get the list of subaccounts defined for the account, optionally filtered by a prefix
  • add(string key, string id, string name, string notes, integer custom_quota)
    Add a new subaccount
  • info(string key, string id)
    Given the ID of an existing subaccount, return the data about it
  • update(string key, string id, string name, string notes, integer custom_quota)
    Update an existing subaccount
  • delete(string key, string id)
    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(string key, string id)
    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(string key, string id)
    Resume a paused subaccount's sending

Inbound Calls

  • domains(string key)
    List the domains that have been configured for inbound delivery
  • add-domain(string key, string domain)
    Add an inbound domain to your account
  • check-domain(string key, string domain)
    Check the MX settings for an inbound domain. The domain must have already been added with the add-domain call
  • delete-domain(string key, string domain)
    Delete an inbound domain from the account. All mail will stop routing for this domain immediately.
  • routes(string key, string domain)
    List the mailbox routes defined for an inbound domain
  • add-route(string key, string domain, string pattern, string url)
    Add a new mailbox route to an inbound domain
  • update-route(string key, string id, string pattern, string url)
    Update the pattern or webhook of an existing inbound mailbox route. If null is provided for any fields, the values will remain unchanged.
  • delete-route(string key, string id)
    Delete an existing inbound mailbox route
  • send-raw(string key, string raw_message, array|null to, string mail_from, string helo, string client_address)
    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

Exports Calls

  • info(string key, string id)
    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(string key)
    Returns a list of your exports.
  • rejects(string key, string notify_email)
    Begins an export of your rejection blacklist. The blacklist 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.
  • whitelist(string key, string notify_email)
    Begins an export of your rejection whitelist. The whitelist will be exported to a zip archive containing a single file named whitelist.csv that includes the following fields: email, detail, created_at.
  • activity(string key, string notify_email, string date_from, string date_to, array tags, array senders, array states, array api_keys)
    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 Calls

  • list(string key)
    Lists your dedicated IPs.
  • info(string key, string ip)
    Retrieves information about a single dedicated ip.
  • provision(string key, boolean warmup, string pool)
    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-warmup(string key, string ip)
    Begins the warmup process for a dedicated IP. During the warmup process, Mandrill 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-warmup(string key, string ip)
    Cancels the warmup process for a dedicated IP.
  • set-pool(string key, string ip, string pool, boolean create_pool)
    Moves a dedicated IP to a different pool.
  • delete(string key, string ip)
    Deletes a dedicated IP. This is permanent and cannot be undone.
  • list-pools(string key)
    Lists your dedicated IP pools.
  • pool-info(string key, string pool)
    Describes a single dedicated IP pool.
  • create-pool(string key, string pool)
    Creates a pool and returns it. If a pool already exists with this name, no action will be performed.
  • delete-pool(string key, string pool)
    Deletes a pool. A pool must be empty before you can delete it, and you cannot delete your default pool.
  • check-custom-dns(string key, string ip, string domain)
    Tests whether a domain name is valid for use as the custom reverse DNS for a dedicated IP.
  • set-custom-dns(string key, string ip, string domain)
    Configures the custom DNS name for a dedicated IP.

Metadata Calls

  • list(string key)
    Get the list of custom metadata fields indexed for the account.
  • add(string key, string name, string view_template)
    Add a new custom metadata field to be indexed for the account.
  • update(string key, string name, string view_template)
    Update an existing custom metadata field.
  • delete(string key, string name)
    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.