> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailtrap

> Connect Mailtrap to your Atako agents — 26 read and 7 write actions.

Let your agents read the Mailtrap email sandbox (projects, inboxes, captured messages with their text, HTML, headers, spam score and HTML check), check sending domains, stats, email logs and suppressions, and manage email templates, contacts and contact lists. Sending is not included.

## Connection

* **Authentication**: API key (API token).

> [!NOTE]
>
> Sign in at mailtrap.io → Settings → API Tokens → Add Token. Name it, pick the account, and give it the permission matching what the agent should do on each resource: Viewer is enough to read, Admin is needed to create or update templates, contacts and lists and to mark sandbox messages as read. Copy the token (shown once).
>
> See [Mailtrap's documentation](https://mailtrap.io/settings/api-tokens).

## Read actions (26)

| Action | Description |
| - | - |
| `get_contact` | Contacts are written asynchronously: for a few seconds after a create or an update, get\_contact can answer 404 and another update 409 "Contact exists or being updated" (wait \~5 s and retry). Get one contact by id (string UUID) or by e-mail address (string), from list\_contacts. |
| `get_email_log` | Get one sent-email log with its delivery events (open, click, bounce…). Argument: sending\_message\_id (string, the message\_id from list\_email\_logs). The raw-message link is removed. |
| `get_email_template` | Get one email template. Id from list\_email\_templates. |
| `get_message_headers` | Get the mail headers of a captured message. |
| `get_message_html` | A message sent as plain text has no HTML part: this action then answers 404 (use get\_message\_text). Get the HTML body of a captured message, rendered (returned as a string). |
| `get_message_html_analysis` | Get the HTML check of a captured message: the markup rules that email clients (desktop, mobile, web) do not support. |
| `get_message_spam_report` | Get the SpamAssassin report of a captured message (score, threshold, rule details). |
| `get_message_text` | Get the plain-text body of a captured message (returned as a string). |
| `get_sandbox` | Get one sandbox (inbox) by id, from list\_sandboxes. The SMTP password is removed. |
| `get_sandbox_message` | Get one captured message (subject, sender, recipient, size, read flag, blacklist and SMTP info). Message id from list\_sandbox\_messages. |
| `get_sending_stats` | Get the account sending totals over a period: delivery, bounce, open, click and spam counts and rates. start\_date and end\_date are required (YYYY-MM-DD strings); optional filters domain\_ids (array of integers), sending\_streams (array of strings: transactional, bulk), categories (array of strings). |
| `get_sending_stats_by_category` | Same sending stats, one row per email category. Arguments as get\_sending\_stats (start\_date and end\_date required, YYYY-MM-DD strings). |
| `get_sending_stats_by_date` | Same sending stats, one row per day. Arguments as get\_sending\_stats (start\_date and end\_date required, YYYY-MM-DD strings). |
| `get_sending_stats_by_domain` | Same sending stats, one row per sending domain. Arguments as get\_sending\_stats (start\_date and end\_date required, YYYY-MM-DD strings). |
| `list_accounts` | List the Mailtrap accounts the token can access (id, name, access\_levels). |
| `list_contact_fields` | List the custom contact fields (id, name, data\_type, merge\_tag). The merge\_tag is the key to use in the fields object of create\_contact / update\_contact. |
| `list_contact_lists` | List the contact lists (id, name). Optional search (string, part of the name). |
| `list_contacts` | List contacts. Optional: list\_id (integer, from list\_contact\_lists), status (string: subscribed, unsubscribed), email (string, case-insensitive substring), per\_page (integer, 1 to 50, default 25), token (string: the pagination next\_token of the previous answer). |
| `list_email_logs` | List the sent-email logs (status, subject, sender, recipient, opens and clicks). Optional filters: sent\_after, sent\_before (ISO 8601 date-time strings), status (string: delivered, not\_delivered, enqueued, opted\_out), to, from, subject (strings, contains match), category (string, exact), domain\_id (integer, from list\_sending\_domains), sending\_stream (string: transactional, bulk). Paging: pass the next\_page\_cursor of the previous answer as search\_after (string). |
| `list_email_templates` | List the email templates (id, name, category, subject, text and HTML bodies). |
| `list_message_attachments` | List the attachments of a captured message (metadata only: file name, type, size; no content). Optional attachment\_type (string: inline or attachment). |
| `list_projects` | List the projects with their sandboxes (inboxes). Passwords and share links are removed. |
| `list_sandbox_messages` | List the messages captured in a sandbox, newest first. Optional: search (matches subject, recipient e-mail and name), page (page number), last\_id (returns the page of messages before this message id, overrides page). |
| `list_sandboxes` | List the sandboxes (inboxes) of the account with message counts. The SMTP password is removed. |
| `list_sending_domains` | List the sending domains with their DNS verification status, compliance status and tracking settings. |
| `list_suppressions` | List the suppressed addresses (hard bounce, unsubscription, spam complaint, manual import). Optional: email (string, exact address), start\_time and end\_time (ISO 8601 date-time strings), last\_id (string, id of the last suppression of the previous page). |

## Write actions (7)

| Action | Description |
| - | - |
| `create_contact` | Contacts are written asynchronously: for a few seconds after a create or an update, get\_contact can answer 404 and another update 409 "Contact exists or being updated" (wait \~5 s and retry). Create a contact. Arguments: email (string, required); fields (object keyed by merge\_tag from list\_contact\_fields, e.g. \{"first\_name":"Ana"}); list\_ids (array of integers, from list\_contact\_lists). |
| `create_contact_list` | Create a contact list. Argument: name (string). |
| `create_email_template` | Create an email template. Arguments: name, category, subject (strings, max 255 characters each, required); body\_text, body\_html (strings, optional). |
| `mark_sandbox_all_read` | Mark every message of a sandbox as read. Argument: sandbox\_id (integer, from list\_sandboxes). Returns the sandbox without its password. |
| `update_contact` | Contacts are written asynchronously: for a few seconds after a create or an update, get\_contact can answer 404 and another update 409 "Contact exists or being updated" (wait \~5 s and retry). Update a contact (created if unknown). Arguments: contact\_identifier (string, UUID or e-mail); email (string, required, the contact e-mail); fields (object keyed by merge\_tag); list\_ids\_included, list\_ids\_excluded (arrays of integers: lists to add to / remove from); unsubscribed (boolean). |
| `update_email_template` | Update an email template. Arguments: email\_template\_id (integer); name, category, subject (strings, max 255 characters each, all required: resend the current value to keep it); body\_text, body\_html (strings, optional). |
| `update_sandbox_message` | Mark a captured message as read or unread. Arguments: sandbox\_id (integer), message\_id (integer), is\_read (boolean: true = read, false = unread). |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](https://docs.atako.ai/integrations/permissions.md) for the grant model and [Security](https://docs.atako.ai/integrations/security.md) for how credentials are protected.

***

*Last reviewed against the provider API: October 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.