Manage Mailtrap marketing contacts and campaign audiences

This skill covers Mailtrap's Contacts API, the marketing database behind campaign audiences: lists, segments, custom fields, and bulk imports, plus custom events for triggering automations. It draws a hard line the skill itself emphasizes: contacts and their list/segment/consent attributes decide who is eligible for a marketing campaign, while Suppressions - hard bounces, spam complaints, unsubscribes - live on the sending side and block delivery on send streams entirely; the two systems are separate and must not be conflated.

Use it for programmatic contact management (create, update, bulk import), syncing contacts with a CRM or data warehouse, list cleanup via CSV import, updating custom fields or firing custom events for automations, or building segments and custom fields for audience targeting. Before generating any request body, the skill points to checking Mailtrap's Contacts OpenAPI spec directly, since field names and required parameters can change. Blocking a recipient from receiving sends is explicitly out of scope here - that's the Suppressions system covered by the related mailtrap-sending-emails skill.

All endpoints require Authorization: Bearer $MAILTRAP_API_TOKEN and an $MAILTRAP_ACCOUNT_ID resolved via GET /api/accounts. Core operations: contact CRUD at /accounts/{id}/contacts, bulk import at /contacts/imports (an async job, polled via GET .../imports/{import_id}, capped at 50,000 contacts per request), contact lists and custom fields at their own sub-paths, custom events posted as {name, params} to /contacts/{contact_identifier}/events, and contact export. The typical rate limit is 200 requests per 60 seconds per account, which is why bulk import is recommended over one-by-one creates for large loads. A single contact create takes an email, a fields object (e.g. first_name, company), and list_ids; bulk import takes an array of similarly-shaped contact objects.

curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/imports" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -d '{"contacts": [{"email": "user1@example.com", "fields": {"first_name": "John"}}]}'

Sync can run through the Contacts API directly (real-time or scheduled from your own code) or through no-code tools like Zapier, Make, or n8n. Lists are explicitly-defined contact groups, segments are dynamic groups, and custom events feed Mailtrap's automations product; contacts maintained here are the audience source for the separate Campaigns product covering authoring and scheduling.

Developers integrating Mailtrap's marketing contact database with a CRM, data warehouse, or CSV import pipeline, who need to manage lists, segments, and custom fields at scale via bulk import rather than hitting rate limits with individual create calls, and who need to keep marketing eligibility clearly separate from sending-side suppression blocks.