managing-contacts
Use when using Mailtrap Contacts API or UI to add, update, bulk import, list, segment marketing contacts, custom fields, or custom events. Use when syncing contacts from a CRM or warehouse, or building audiences for campaigns.
How do I install this agent skill?
npx skills add https://github.com/mailtrap/mailtrap-skills --skill managing-contactsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a legitimate documentation resource for managing contacts via the Mailtrap API. It provides endpoint references, standard authorization instructions, and example curl commands using environment variables for sensitive tokens. No security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 skill sending-emails.
Related skills: authorizing-api-requests (tokens, env vars, account_id resolution), 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. See skill authorizing-api-requests for token scope, storage, and the one-liner that resolves $MAILTRAP_ACCOUNT_ID from GET https://mailtrap.io/api/accounts.
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 .../eventswith an eventnameandparamsobject 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 |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/mailtrap/mailtrap-skills/managing-contacts">View managing-contacts on skillZs</a>