7.2 KiB

Raw Permalink Blame History

name	description	risk	source	date_added
mailtrap-managing-contacts	Manage Mailtrap contacts, lists, segments, custom fields, imports, CRM syncs, and campaign audiences through the UI or API.	critical	community	2026-06-19

Managing Mailtrap contacts

Overview

Before generating API request bodies: check the Contacts OpenAPI spec for current field names, required parameters, and nested structures.

Contacts are the marketing database: lists, segments, custom fields, and imports for campaign audiences and related workflows. The Contacts API automates create/update and can feed CRM or CDP sync (your code, or tools like Zapier, Make, n8n — see Import contacts).

Suppressions (hard bounces, spam complaints, unsubscribes on the sending side) live in the sending product and block delivery for those addresses on your streams. That is applied separately from marketing filters (segments, list membership, consent flags) that decide who is eligible for campaigns. For sending-side blocks, see Suppressions and mailtrap-sending-emails.

Related skills: mailtrap-sending-emails (live send paths).

When to use

Programmatic contact management (create, update, bulk import)
Sync with CRMs or data warehouses
Contact list cleanup and CSV import
Updating contacts with custom fields or firing custom events for automations
Segments and custom fields for audience building

Authorization

All endpoints below need Authorization: Bearer $MAILTRAP_API_TOKEN and an $MAILTRAP_ACCOUNT_ID in the path. Resolve $MAILTRAP_ACCOUNT_ID from GET https://mailtrap.io/api/accounts, and store tokens in environment variables or a secrets manager.

Endpoints (replace placeholders)

Action	Method	URL	Reference
Create / get / update / delete contact	various	`https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts`	Contacts
Bulk import (async job)	`POST`	`https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/imports`	Bulk import
Contact lists	various	`https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/lists`	Contact lists
Custom fields	various	`https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/fields`	Contact fields
Custom events	`POST`	`https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/{contact_identifier}/events`	Contact events
Export contacts	various	`https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/exports`	Export contacts

Rate limit (typical): 200 requests per 60 seconds per account — prefer bulk import for large loads.
Bulk import limit: up to 50,000 contacts per import request (async job); poll import status with GET .../contacts/imports/{import_id}. See Bulk import.

Examples (`curl`)

Single contact create (with custom fields)

curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": {
      "email": "john.smith@example.com",
      "fields": {"first_name": "John", "last_name": "Smith", "company": "Example Inc"},
      "list_ids": [1, 2, 3]
    }
  }'

Bulk import (array of contacts)

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

Custom event (event name + payload)

curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/{contact_identifier}/events" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "UserLogin", "params": {"user_id": 101, "is_active": true}}'

Concepts

Lists — explicitly defined list of contacts.
Segments — dynamic groups; see Segments.
Custom fields — properties like first and last name or membership level; see Custom fields.
Custom events — POST .../events with an event name and params object for automations.

CRM and sync

API: suitable for real-time or scheduled sync from your CRM or database.
No-code: Zapier, Make.com, n8n per Import contacts – third-party tools.

Campaigns use case

Contacts power marketing campaigns: you maintain clean lists, consent, and attributes here; campaign authoring and scheduling are product features documented in Campaigns.

Common mistakes

Mistake	Fix
Hitting rate limits with one-by-one creates	Use `/contacts/imports` for bulk loads (respect 50k per request) and backoff
Treating marketing contacts as sending suppressions	Use Suppressions for blocked recipients on send streams

Limitations

Contact API shapes can change; check Mailtrap's current OpenAPI spec before generating request bodies.

7.2 KiB Raw Permalink Blame History Unescape Escape