Skip to content

MT-20453: Add missing cURL code samples and make cURL default option #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mklocek merged 1 commit into from
Jan 29, 2026
Merged

MT-20453: Add missing cURL code samples and make cURL default option #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions .claude/skills/gitbook-assistant/.SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,8 +244,7 @@ Only load the full reference when user asks specific questions about advanced fe
# OpenAPI specs

- Use SDKs for language-specific client libraries examples
- Prioritize such languages in this order: PHP, Node.js, Python, Ruby, .NET, Java, cURL, HTTP
- Gitbook generated cURL and HTTP examples automatically from the specs, don't hardcode those code examples into x-code-samples.
- Prioritize such languages in this order: cURL, Node.js, PHP, Python, Ruby, .NET, Java
- If some API method isn't covered with Node.JS SDK and Python SDK - let Gitbook generate those examples
- Use code samples based on Mailtrap SDK examples
- Use Context7 MCP to query info about SDK capabilities
Expand All @@ -254,4 +253,4 @@ Only load the full reference when user asks specific questions about advanced fe
- Add reference to features in the OpenAPI spec and build relative links to them to the relevant sections of the documentation
- Build OpenAPI specs file(s) in /openapi/ directory
- They or one for all will be imported into the Gitbook documentation
- If SDK doesn't support some method - mention it in code sample
- If SDK doesn't support some method - mention it in code sample
15 changes: 7 additions & 8 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,13 +138,13 @@ description: |
### SDK Priority Order

Include code samples in this order:
1. Node.js (JavaScript)
2. PHP
3. Python
4. Ruby
5. .NET (C#)
6. Java
7. cURL (shell)
1. cURL (shell)
2. Node.js (JavaScript)
3. PHP
4. Python
5. Ruby
6. .NET (C#)
7. Java

### Code Sample Format

Expand All @@ -171,7 +171,6 @@ x-codeSamples:
### Code Sample Guidelines

- **Use official Mailtrap SDKs** for language-specific examples
- **GitBook auto-generates cURL and HTTP** examples - don't hardcode these unless necessary
- **If SDK doesn't support a method**, either let GitBook generate the example or add a comment noting SDK limitations
- **Use environment variables** for API keys (e.g., `process.env.MAILTRAP_API_KEY`)
- **Use Context7 MCP** to query SDK capabilities when unsure
Expand Down
117 changes: 117 additions & 0 deletions specs/contacts.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,17 @@ paths:
tags:
- Contacts
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/contacts \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"email": "john.smith@example.com",
"fields": {"first_name": "John", "last_name": "Smith", "company": "Example Inc"},
"list_ids": [1, 2, 3]
}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -302,6 +313,11 @@ paths:
tags:
- Contacts
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/{contact_identifier} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -450,6 +466,13 @@ paths:
description: Update contact using UUID or email (URL encoded)
operationId: updateContact
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/contacts/{contact_identifier} \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"email": "new@example.com", "fields": {"first_name": "John"}}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -583,6 +606,11 @@ paths:
description: Delete contact using UUID or email (URL encoded)
operationId: deleteContact
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X DELETE https://mailtrap.io/api/accounts/{account_id}/contacts/{contact_identifier} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -665,6 +693,13 @@ paths:
tags:
- Contact Events
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/contacts/{contact_identifier}/events \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "UserLogin", "params": {"user_id": 101, "is_active": true}}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -784,6 +819,13 @@ paths:
tags:
- Contact Exports
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/contacts/exports \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"filters": [{"name": "list_id", "operator": "equal", "value": [1, 2]}]}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -897,6 +939,11 @@ paths:
tags:
- Contact Exports
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/exports/{export_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -990,6 +1037,13 @@ paths:
tags:
- Contact Imports
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/contacts/imports \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"contacts": [{"email": "user1@example.com", "fields": {"first_name": "John"}, "list_ids_included": [1, 2]}]}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1128,6 +1182,11 @@ paths:
tags:
- Contact Imports
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/imports/{import_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1222,6 +1281,11 @@ paths:
tags:
- Contact Lists
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/lists \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1308,6 +1372,13 @@ paths:
tags:
- Contact Lists
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/contacts/lists \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "Customers"}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1403,6 +1474,11 @@ paths:
tags:
- Contact Lists
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/lists/{list_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1482,6 +1558,13 @@ paths:
tags:
- Contact Lists
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/contacts/lists/{list_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "Former Customers"}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1579,6 +1662,11 @@ paths:
tags:
- Contact Lists
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X DELETE https://mailtrap.io/api/accounts/{account_id}/contacts/lists/{list_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1657,6 +1745,11 @@ paths:
tags:
- Contact Fields
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/fields \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1748,6 +1841,13 @@ paths:
tags:
- Contact Fields
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/contacts/fields \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "Company", "data_type": "text", "merge_tag": "company"}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1877,6 +1977,11 @@ paths:
tags:
- Contact Fields
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X GET https://mailtrap.io/api/accounts/{account_id}/contacts/fields/{field_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -1960,6 +2065,13 @@ paths:
tags:
- Contact Fields
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/contacts/fields/{field_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "Updated Name", "merge_tag": "updated_name"}'
- lang: javascript
label: Node.js
source: |
Expand Down Expand Up @@ -2079,6 +2191,11 @@ paths:
tags:
- Contact Fields
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X DELETE https://mailtrap.io/api/accounts/{account_id}/contacts/fields/{field_id} \
-H 'Authorization: Bearer YOUR_API_TOKEN'
- lang: javascript
label: Node.js
source: |
Expand Down
Loading