--- title: Mailtrap API Integration on Truto slug: mailtrap category: Email canonical: "https://truto.one/integrations/detail/mailtrap/" --- # Mailtrap API Integration on Truto **Category:** Email **Status:** Generally available ## MCP-ready AI tools Truto exposes 42 tools for Mailtrap that AI agents can call directly. - **list_all_mailtrap_domains** — List Mailtrap sending domains and their verification status. Returns each domain with id, domain_name, compliance_status, dns_verified, dns_records, tracking settings, alert settings, and permissions. - **create_a_mailtrap_domain** — Create a Mailtrap domain for email authentication. After creation, verify the domain by adding the returned DNS records (SPF, DKIM, DMARC). Returns the created domain with id, domain_name, compliance_status, and dns_records. Required: domain (containing domain_name). - **get_single_mailtrap_domain_by_id** — Get a Mailtrap sending domain by id. Returns id, domain_name, compliance_status, dns_verified, dns_records, tracking settings, alert settings, and permissions. Required: id. - **update_a_mailtrap_domain_by_id** — Update configuration settings (open/click tracking, auto-unsubscribe link) for a Mailtrap domain by id. Returns the updated domain record. Required: id, domain. - **delete_a_mailtrap_domain_by_id** — Delete a Mailtrap domain by id. Returns an empty 204 response on success. Required: id. - **create_a_mailtrap_domain_send_setup_instruction** — Send Mailtrap DNS setup instructions for a domain. Returns an empty 204 response on success. Required: domain_id, email. - **list_all_mailtrap_domain_company_infos** — Get company information associated with a Mailtrap domain / account. Company info is required for domain compliance verification. Returns: name, address, city, country, phone, zip_code, privacy_policy_url, terms_of_service_url, website_url, info_level. Required: domain_id. - **create_a_mailtrap_domain_company_info** — Create company information for a Mailtrap domain / account. Company info is required for domain compliance verification. Returns the created company info record. Required: domain_id, company_info (with name, address, city, country, zip_code, website_url). - **update_a_mailtrap_domain_company_info_by_id** — Update company information for a Mailtrap domain / account. All fields are optional; only provided fields are updated. Returns the updated company info record. Required: domain_id, company_info. - **list_all_mailtrap_suppressions** — List and search suppressed email addresses in Mailtrap. Returns an array of suppression objects (up to 1000 per request). Use last_id for cursor-based pagination. Suppressed addresses will not receive any emails from the account. Rate limit: 10 requests per minute per account. - **create_a_mailtrap_suppression** — Add an email address to the Mailtrap suppression list. Suppressed addresses will not receive any emails from the account. Requires admin-level access. Rate limit: 10 requests per minute per account. Returns the created suppression. Required: email, domain_id, sending_stream. - **delete_a_mailtrap_suppression_by_id** — Remove an email from the Mailtrap suppression list to allow sending again. Requires admin-level access. Returns the deleted suppression record. Required: id (the suppression UUID). - **list_all_mailtrap_stats** — Get Mailtrap account sending stats (the same aggregates shown in the Stats dashboard). Returns delivery, bounce, open, click, and spam counts and rates. Required: start_date, end_date. Supports domain, sending stream, category, and ESP filters. - **list_all_mailtrap_stats_domains** — Get Mailtrap account sending stats grouped by domain. Returns an array of entries with domain_id and stats (delivery, bounce, open, click, spam counts and rates). Required: start_date, end_date. Supports domain, sending stream, category, and ESP filters. - **list_all_mailtrap_stats_categories** — List Mailtrap account sending stats grouped by category. Returns: category, stats. Supports optional filters. - **list_all_mailtrap_stats_email_service_providers** — List Mailtrap sending stats grouped by email service provider. Returns: email_service_provider, stats. Supports optional date, domain, stream, category, and ESP filters. - **list_all_mailtrap_stats_dates** — List Mailtrap account sending stats by date. Returns an array of daily entries, each containing date and stats. - **list_all_mailtrap_email_logs** — List email logs (messages) for a Mailtrap account. Returns each log with id, message_id, sent_at, created_at, and updated_at. Invalid or unknown filter values are ignored. - **get_single_mailtrap_email_log_by_id** — Get a single Mailtrap email log by its message id. Returns the message including id, message_id, sent_at, created_at, and updated_at. Required: id. - **list_all_mailtrap_webhooks** — List Mailtrap webhooks associated with the account. Returns: id, url, active, webhook_type, payload_format, sending_stream, domain_id, event_types. - **create_a_mailtrap_webhook** — Create a Mailtrap webhook for the account. Returns the new webhook including id, url, webhook_type, payload_format, active, and signing_secret. Required: webhook (must include url and webhook_type). - **get_single_mailtrap_webhook_by_id** — Get a Mailtrap webhook by id. Returns: id, url, active, webhook_type, payload_format, sending_stream, domain_id, event_types. Required: id. - **update_a_mailtrap_webhook_by_id** — Update an existing Mailtrap webhook by id. Returns the updated webhook object including id, url, webhook_type, payload_format, active, and event_types. Required: id, webhook. - **delete_a_mailtrap_webhook_by_id** — Delete a Mailtrap webhook by id. Returns the deleted webhook object including id, url, webhook_type, payload_format, and active. Required: id. - **create_a_mailtrap_contact** — Create a new Mailtrap contact. Returns the created contact with id, email, status, fields, list_ids, created_at, and updated_at. Required: email. - **update_a_mailtrap_contact_by_id** — Update an existing Mailtrap contact by UUID or URL-encoded email. Returns: action, data. Required: contact_identifier. - **delete_a_mailtrap_contact_by_id** — Delete a Mailtrap contact by UUID or URL-encoded email. Returns an empty 204 response on success. Required: contact_identifier. - **create_a_mailtrap_contacts_export** — Create a new contact export in Mailtrap. Returns the export record including id, status, created_at, updated_at, and url. - **get_single_mailtrap_contacts_export_by_id** — Get a single contact export in Mailtrap by id. Returns the export record including id, status, created_at, updated_at, and url. Required: id. - **create_a_mailtrap_contacts_import** — Import contacts in bulk to mailtrap, with automatic updates for matching emails and support for custom fields and list management. Returns the import object including id, status, created_contacts_count, updated_contacts_count, and contacts_over_limit_count. Supports up to 50,000 contacts per request; imports run asynchronously, so poll by id to track completion. - **get_single_mailtrap_contacts_import_by_id** — Get a mailtrap contact import by id. Returns the import object, including id, status, created_contacts_count, updated_contacts_count, and contacts_over_limit_count. Required: id. - **list_all_mailtrap_contacts_lists** — List all Mailtrap contact lists in your account. Returns each list's id and name. - **create_a_mailtrap_contacts_list** — Create a new Mailtrap contact list. Returns the created list including id and name. Required: name. - **get_single_mailtrap_contacts_list_by_id** — Get a single Mailtrap contact list by id. Returns the list's id and name. Required: id. - **update_a_mailtrap_contacts_list_by_id** — Update an existing contact list in Mailtrap. Returns: id, name. Required: id. Request body accepts name, up to 255 characters. - **delete_a_mailtrap_contacts_list_by_id** — Delete a contact list in Mailtrap. Returns an empty 204 response on success. Required: id. - **list_all_mailtrap_contacts_fields** — List all contact fields in your Mailtrap account. Returns: id, name, data_type, merge_tag. - **create_a_mailtrap_contacts_field** — Create a new contact field in Mailtrap. Returns: id, name, data_type, merge_tag. Account limit of 40 fields. - **get_single_mailtrap_contacts_field_by_id** — Get a single Mailtrap contact field by id. Returns: id, name, data_type, merge_tag. Required: id. - **update_a_mailtrap_contacts_field_by_id** — Update an existing Mailtrap contact field by id. Returns the updated field's id, name, data_type, and merge_tag. Required: id. You cannot change the field's data_type. - **delete_a_mailtrap_contacts_field_by_id** — Delete an existing Mailtrap contact field by id. Returns an empty 204 response on success. Required: id. Cannot delete a field used in active automations, started or scheduled campaigns, or segment conditions. - **create_a_mailtrap_contacts_event** — Create an event for a Mailtrap contact. Returns an empty 204 response on success. Required: contact_identifier. ## How it works 1. **Link your customer's Mailtrap account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Mailtrap.** The Proxy API is a 1-to-1 mapping of the Mailtrap API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Sync CRM audiences into Mailtrap for lifecycle campaigns** — Let your users push segmented contacts and custom fields from your CRM or CDP into Mailtrap lists, so they can trigger personalized transactional and marketing emails without manual CSV exports. - **White-label sending domains for multi-tenant platforms** — Website builders, e-commerce platforms, and vertical SaaS can programmatically provision sender domains and submit compliance info on behalf of each tenant, then surface SPF/DKIM records inside their own UI. - **Unified email deliverability reporting** — Pull daily send stats, bounce rates, opens, and clicks into your analytics or BI product so users see Mailtrap performance next to their other marketing channels. - **Cross-platform suppression and compliance sync** — Compliance and support tools can propagate opt-outs, GDPR deletion requests, and hard bounces into Mailtrap's suppression list to guarantee no further sends to flagged addresses. - **Real-time email event ingestion via webhooks** — Register your app's endpoint on your users' Mailtrap accounts to receive delivery, bounce, and complaint events, powering in-app inboxes, alerts, or automated workflows. ## What you can build - **Bulk contact import pipeline** — Push up to 50,000 contacts asynchronously into a user's Mailtrap account with mapped custom fields and list assignments. - **Automated domain onboarding flow** — Create a sending domain, submit company/compliance info, and render the returned DNS records so your users verify their domain without leaving your product. - **Deliverability analytics dashboard** — Aggregate stats by date, domain, category, and ESP to display bounce, open, and click metrics inside your own reporting UI. - **Suppression list manager** — Give users an in-app view to add, list, and remove suppressed addresses in Mailtrap, backed by your existing opt-out logic. - **Webhook auto-provisioning** — Register and manage Mailtrap webhooks on behalf of users so your product receives real-time email events without them touching Mailtrap settings. - **Email log explorer** — Fetch and display per-message logs so support and ops teams can debug delivery issues for a specific recipient directly inside your product. ## FAQs ### How do end users authenticate their Mailtrap account? Mailtrap uses API token authentication. Through Truto, your users provide their Mailtrap API token during the connection flow, and Truto handles secure storage and token injection on every request. ### Can I sync custom contact fields from my product into Mailtrap? Yes. You can create and manage custom contact fields via the contacts fields endpoints, then map your product's data model to them when creating or importing contacts. ### What's the best way to load large contact lists? Use the contacts import endpoint, which accepts asynchronous batches of up to 50,000 contacts per job. You can then poll the import status endpoint to track completion instead of creating contacts one at a time. ### Can I provision sending domains for my customers programmatically? Yes. You can create a domain, attach company info for compliance, and retrieve the domain record (including DNS setup details) so your customers verify SPF/DKIM/DMARC from within your UI. ### How do I get real-time delivery and bounce events? Register a webhook on the user's Mailtrap account pointing to your endpoint. Mailtrap will push delivery, bounce, open, and complaint events as they happen, so you don't need to poll stats or logs. ### How fresh is analytics data from Mailtrap? Stats endpoints return aggregates by date, domain, category, and ESP and are typically updated on a near-real-time to daily cadence. For event-level freshness, pair stats polling with webhooks for real-time delivery events. ## Related reading - [Connect Mailtrap to ChatGPT: Manage Domains and Analyze Sending Stats](https://truto.one/blog/connect-mailtrap-to-chatgpt-manage-domains-and-analyze-sending-stats/) — Learn how to connect Mailtrap to ChatGPT using a managed MCP server. Automate domain verification, sending stats, and suppression list management using AI. - [Connect Mailtrap to Claude: Sync Contact Lists and Manage Custom Fields](https://truto.one/blog/connect-mailtrap-to-claude-sync-contact-lists-and-manage-custom-fields/) — Learn how to connect Mailtrap to Claude using a managed MCP server. Automate domain verification, contact imports, custom field management, and email log analysis. - [Connect Mailtrap to ChatGPT: Manage email domains and sending stats](https://truto.one/blog/connect-mailtrap-to-chatgpt-manage-email-domains-and-sending-stats/) — Learn how to connect Mailtrap to ChatGPT using Truto's managed MCP server. Step-by-step guide to generating domains, tracking stats, and securely automating email ops. - [Connect Mailtrap to Claude: Handle contacts, lists, and delivery data](https://truto.one/blog/connect-mailtrap-to-claude-handle-contacts-lists-and-delivery-data/) — Learn how to connect Mailtrap to Claude using a managed MCP server. Automate domain compliance, manage suppression lists, and execute email workflows.