Connection
- Authentication: API key (API token).
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.
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 for the grant model and Security for how credentials are protected.Last reviewed against the provider API: October 2026.