Skip to content

Update nodejs documentation #11

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
yanchuk merged 9 commits into from
Jan 14, 2026
Merged

Update nodejs documentation #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
146ee76
Refactor JavaScript examples in OpenAPI specifications to use async f…
narekhovhannisyan Jan 13, 2026
eb14e89
Refactor email batch sending example in OpenAPI specifications to use…
narekhovhannisyan Jan 13, 2026
4436b7b
Refactor email sending example in OpenAPI specifications to encapsula…
narekhovhannisyan Jan 13, 2026
1b9ce02
Encapsulate email sending logic in an async function within OpenAPI s…
narekhovhannisyan Jan 13, 2026
0fcb4fe
Refactor JavaScript examples in OpenAPI specifications to encapsulate…
narekhovhannisyan Jan 13, 2026
ea60bf7
Refactor JavaScript examples in OpenAPI specifications to encapsulate…
narekhovhannisyan Jan 13, 2026
9ab8960
Update JavaScript examples in OpenAPI specifications to use consisten…
narekhovhannisyan Jan 13, 2026
df362c8
Update JavaScript examples in OpenAPI specifications to utilize the n…
narekhovhannisyan Jan 13, 2026
6e53054
Update JavaScript example in OpenAPI specifications to use the correc…
narekhovhannisyan Jan 13, 2026
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
171 changes: 123 additions & 48 deletions specs/email-api.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,11 +72,15 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

const domain = await client.sendingDomains.create({
domain_name: "example.com"
});
async function createDomain() {
const domain = await client.sendingDomains.create({
domain_name: "example.com"
});

console.log("Created domain:", domain);
}

console.log("Created domain:", domain);
createDomain();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -207,9 +211,12 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

const domains = await client.sendingDomains.getList();
async function getDomains() {
const response = await client.sendingDomains.getList();
const domains = response.data;
}

console.log("Sending domains:", domains);
getDomains();
Comment on lines +214 to +219
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Missing output in getDomains function.

The getDomains function retrieves data but doesn't log or return anything useful. Unlike other samples (e.g., createDomain at line 80), this one has no console.log to show the result.

Suggested fix 
 async function getDomains() {
   const response = await client.sendingDomains.getList();
   const domains = response.data;
+
+  console.log("Domains:", domains);
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async function getDomains() {
const response = await client.sendingDomains.getList();
const domains = response.data;
}
console.log("Sending domains:", domains);
getDomains();
async function getDomains() {
const response = await client.sendingDomains.getList();
const domains = response.data;
console.log("Domains:", domains);
}
getDomains();
🤖 Prompt for AI Agents 
In @specs/email-api.openapi.yml around lines 214 - 219, The getDomains function
fetches the domains into the local variable domains but currently neither
returns nor logs them; update getDomains (the async function that calls
client.sendingDomains.getList and assigns response.data to domains) to either
return domains or emit a console.log showing the retrieved domains (e.g.,
console.log('Domains:', domains)) so callers/examples can see the output.

- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -308,10 +315,14 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

const domainId = 12345;
const domain = await client.sendingDomains.get(domainId);
async function getDomain() {
const domainId = 12345;
const domain = await client.sendingDomains.get(domainId);

console.log("Domain details:", domain);
console.log("Domain details:", domain);
}

getDomain();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -410,10 +421,14 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

const domainId = 12345;
await client.sendingDomains.delete(domainId);
async function deleteDomain() {
const domainId = 12345;
await client.sendingDomains.delete(domainId);

console.log("Domain deleted successfully");
console.log("Domain deleted successfully");
}

deleteDomain();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -511,13 +526,17 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

const domainId = 12345;
await client.sendingDomains.sendSetupInstructions(
domainId,
"devops@example.com"
);
async function sendInstructions() {
const domainId = 12345;
await client.sendingDomains.sendSetupInstructions(
domainId,
"devops@example.com"
);

console.log("Setup instructions sent");
console.log("Setup instructions sent");
}

sendInstructions();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -659,15 +678,19 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

// Get all suppressions
const suppressions = await client.suppressions.getList();
async function getSuppressions() {
// Get all suppressions
const suppressions = await client.suppressions.getList();

// Or search for specific email
const filtered = await client.suppressions.getList({
email: "suppressed@example.com"
});
// Or search for specific email
const filtered = await client.suppressions.getList({
email: "suppressed@example.com"
});

console.log("Suppressions:", suppressions);
}

console.log("Suppressions:", suppressions);
getSuppressions();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -825,10 +848,14 @@ paths:
accountId: YOUR_ACCOUNT_ID
});

const suppressionId = "abc123-def456";
const result = await client.suppressions.delete(suppressionId);
async function deleteSuppression() {
const suppressionId = "abc123-def456";
const result = await client.suppressions.delete(suppressionId);

console.log("Suppression removed:", result);
}

console.log("Suppression removed:", result);
deleteSuppression();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -937,8 +964,12 @@ paths:
source: |
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const templates = await client.templates.getAll();
templates.forEach(tpl => console.log(`${tpl.name}: ${tpl.uuid}`));

async function getTemplates() {
const templates = await client.templates.getList();
}

getTemplates();
Comment on lines +967 to +972
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Missing output in getTemplates function.

The getTemplates function retrieves templates but doesn't output them. Other samples in this file log their results for consistency.

Suggested fix 
 async function getTemplates() {
   const templates = await client.templates.getList();
+
+  console.log("Templates:", templates);
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async function getTemplates() {
const templates = await client.templates.getList();
}
getTemplates();
async function getTemplates() {
const templates = await client.templates.getList();
console.log("Templates:", templates);
}
getTemplates();
🤖 Prompt for AI Agents 
In @specs/email-api.openapi.yml around lines 967 - 972, The getTemplates
function calls client.templates.getList() but never outputs the result; update
the getTemplates function (and its invocation getTemplates()) to either return
or log the retrieved templates for consistency with other samples—e.g., capture
the value from client.templates.getList() and call console.log(templates) or
return templates so the output is visible.

- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -1022,14 +1053,19 @@ paths:
source: |
import { MailtrapClient } from "mailtrap";
const client = new MailtrapClient({ token: "YOUR_API_TOKEN" });
const template = await client.templates.create({
name: "Welcome Email",
subject: "Welcome to {{company_name}}!",
category: "onboarding",
body_html: "<h1>Welcome {{user_name}}!</h1>",
body_text: "Welcome {{user_name}}!"
});
console.log(`Template created: ${template.uuid}`);

async function createTemplate() {
const template = await client.templates.create({
name: "Welcome Email",
subject: "Welcome to {{company_name}}!",
category: "onboarding",
body_html: "<h1>Welcome {{user_name}}!</h1>",
body_text: "Welcome {{user_name}}!"
});
console.log(`Template created: ${template.uuid}`);
}

createTemplate();
- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -1164,8 +1200,13 @@ paths:
source: |
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const template = await client.templates.get(templateId);
console.log(`Template: ${template.name} (UUID: ${template.uuid})`);

async function getTemplate() {
const template = await client.templates.get(templateId);
console.log(`Template: ${template.name} (UUID: ${template.uuid})`);
}

getTemplate();
Comment on lines +1203 to +1209
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

templateId variable is used but not defined.

The templateId variable is referenced but never declared. This would cause a ReferenceError if users copy-paste this code.

Suggested fix 
 async function getTemplate() {
+  const templateId = 12345;
   const template = await client.templates.get(templateId);
   console.log(`Template: ${template.name} (UUID: ${template.uuid})`);
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async function getTemplate() {
const template = await client.templates.get(templateId);
console.log(`Template: ${template.name} (UUID: ${template.uuid})`);
}
getTemplate();
async function getTemplate() {
const templateId = 12345;
const template = await client.templates.get(templateId);
console.log(`Template: ${template.name} (UUID: ${template.uuid})`);
}
getTemplate();
🤖 Prompt for AI Agents 
In @specs/email-api.openapi.yml around lines 1203 - 1209, The snippet calls
client.templates.get(templateId) inside getTemplate but templateId is not
defined; declare or obtain templateId before use (for example accept it as a
function parameter or retrieve it from input/config) and pass it into
getTemplate or set a local const; update the function signature (e.g.,
getTemplate(templateId)) or add a preceding declaration for templateId and
ensure the value is validated before calling client.templates.get so the call to
getTemplate() supplies the defined identifier.

- lang: ruby
label: Ruby
source: |
Expand Down Expand Up @@ -1234,7 +1275,12 @@ paths:
source: |
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const template = await client.templates.update(templateId, { name: "Updated Template", subject: "New Subject" });

async function updateTemplate() {
const template = await client.templates.update(templateId, { name: "Updated Template", subject: "New Subject" });
}

updateTemplate();
Comment on lines +1278 to +1283
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

templateId variable is used but not defined.

Same issue as in getTemplate - the templateId is referenced without being declared.

Suggested fix 
 async function updateTemplate() {
+  const templateId = 12345;
   const template = await client.templates.update(templateId, { name: "Updated Template", subject: "New Subject" });
+
+  console.log("Template updated:", template);
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async function updateTemplate() {
const template = await client.templates.update(templateId, { name: "Updated Template", subject: "New Subject" });
}
updateTemplate();
async function updateTemplate() {
const templateId = 12345;
const template = await client.templates.update(templateId, { name: "Updated Template", subject: "New Subject" });
console.log("Template updated:", template);
}
updateTemplate();
🤖 Prompt for AI Agents 
In @specs/email-api.openapi.yml around lines 1278 - 1283, The updateTemplate
function references templateId which is not declared; fix by providing a valid
templateId value or parameter: either declare a const templateId =
"<existing-template-id>" (or obtain it from client/templates list) before
calling client.templates.update in updateTemplate, or change updateTemplate to
accept templateId as an argument and pass it in when calling updateTemplate();
ensure the same approach is applied consistently as with getTemplate.

- lang: ruby
label: Ruby
source: |
Expand Down Expand Up @@ -1335,7 +1381,12 @@ paths:
source: |
const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
await client.templates.delete(templateId);

async function deleteTemplate() {
await client.templates.delete(templateId);
}

deleteTemplate();
Comment on lines +1384 to +1389
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

templateId variable is used but not defined.

Same issue - templateId is referenced without declaration. Additionally, no logging is present.

Suggested fix 
 async function deleteTemplate() {
+  const templateId = 12345;
   await client.templates.delete(templateId);
+
+  console.log("Template deleted successfully");
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async function deleteTemplate() {
await client.templates.delete(templateId);
}
deleteTemplate();
async function deleteTemplate() {
const templateId = 12345;
await client.templates.delete(templateId);
console.log("Template deleted successfully");
}
deleteTemplate();
🤖 Prompt for AI Agents 
In @specs/email-api.openapi.yml around lines 1384 - 1389, The deleteTemplate
function references an undefined variable templateId and lacks logging; declare
or obtain templateId before using it (e.g., accept it as a parameter to
deleteTemplate or read it from the surrounding scope/inputs) and add a try/catch
inside deleteTemplate that logs success and error details via your logger
(include the templateId in both messages) before calling deleteTemplate();
ensure the function signature and call site are updated consistently to pass the
templateId.

- lang: ruby
label: Ruby
source: |
Expand Down Expand Up @@ -1902,19 +1953,27 @@ components:
title: BadRequestResponse
type: object
properties:
success:
type: boolean
example: false
errors:
type: string
description: Error message
example: Invalid request parameters
type: array
items:
type: string
example: "Invalid request parameters"

RateLimitExceededResponse:
title: RateLimitExceededResponse
type: object
properties:
success:
type: boolean
example: false
errors:
type: string
description: Error message
example: Rate limit exceeded
type: array
items:
type: string
example: "Rate limit exceeded"

ErrorResponse:
type: object
Expand All @@ -1935,13 +1994,21 @@ components:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- "Unauthorized"

Forbidden:
description: Forbidden. Verify domain or check permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- "Forbidden"

NotFound:
description: Resource not found
Expand All @@ -1967,13 +2034,21 @@ components:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
example:
success: false
errors:
- "Invalid request parameters"

LIMIT_EXCEEDED:
description: Rate limit exceeded for the current account.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitExceededResponse'
example:
success: false
errors:
- "Rate limit exceeded"

SendingDomainResponse:
description: Sending domain details
Expand Down
49 changes: 28 additions & 21 deletions specs/email-batch.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,29 +66,28 @@ paths:
// Add bulk: true for Bulk Stream
});

const response = await client.batchSend({
base: {
from: { email: "sender@example.com" },
subject: "Important Update",
text: "Hello {{name}}, we have news for you."
},
requests: [
{
to: [{ email: "user1@example.com" }],
custom_variables: { name: "Alice" }
async function sendBatch() {
const response = await client.batchSend({
base: {
from: { email: "sender@example.com" },
subject: "Important Update",
text: "Hello {{name}}, we have news for you."
},
{
to: [{ email: "user2@example.com" }],
custom_variables: { name: "Bob" }
}
]
});
requests: [
{
to: [{ email: "user1@example.com" }],
custom_variables: { name: "Alice" }
},
{
to: [{ email: "user2@example.com" }],
custom_variables: { name: "Bob" }
}
]
});

response.responses.forEach((result, index) => {
if (result.success) {
console.log(`Email ${index + 1} sent`);
}
});
}

sendBatch();
Comment on lines +69 to +90
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Missing output in sendBatch function.

The sendBatch function makes the API call but doesn't log the response. Other samples in the PR include logging for consistency and developer guidance.

Suggested fix 
 async function sendBatch() {
   const response = await client.batchSend({
     base: {
       from: { email: "sender@example.com" },
       subject: "Important Update",
       text: "Hello {{name}}, we have news for you."
     },
     requests: [
       {
         to: [{ email: "user1@example.com" }],
         custom_variables: { name: "Alice" }
       },
       {
         to: [{ email: "user2@example.com" }],
         custom_variables: { name: "Bob" }
       }
     ]
   });

+  console.log("Batch sent:", response);
 }

 sendBatch();
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async function sendBatch() {
const response = await client.batchSend({
base: {
from: { email: "sender@example.com" },
subject: "Important Update",
text: "Hello {{name}}, we have news for you."
},
{
to: [{ email: "user2@example.com" }],
custom_variables: { name: "Bob" }
}
]
});
requests: [
{
to: [{ email: "user1@example.com" }],
custom_variables: { name: "Alice" }
},
{
to: [{ email: "user2@example.com" }],
custom_variables: { name: "Bob" }
}
]
});
response.responses.forEach((result, index) => {
if (result.success) {
console.log(`Email ${index + 1} sent`);
}
});
}
sendBatch();
async function sendBatch() {
const response = await client.batchSend({
base: {
from: { email: "sender@example.com" },
subject: "Important Update",
text: "Hello {{name}}, we have news for you."
},
requests: [
{
to: [{ email: "user1@example.com" }],
custom_variables: { name: "Alice" }
},
{
to: [{ email: "user2@example.com" }],
custom_variables: { name: "Bob" }
}
]
});
console.log("Batch sent:", response);
}
sendBatch();
🤖 Prompt for AI Agents 
In @specs/email-batch.openapi.yml around lines 69 - 90, The sendBatch function
calls client.batchSend but never returns or logs the response; update sendBatch
(the async function sendBatch and its invocation) to capture the response from
client.batchSend, log or return the response for visibility (e.g., use
console.log or return response) and handle errors (catch and log) to match other
samples' behavior so callers can see success/failure details.

- lang: php
label: PHP
source: |
Expand Down Expand Up @@ -532,13 +531,21 @@ components:
application/json:
schema:
$ref: '#/components/schemas/SendEmailErrorResponse'
example:
success: false
errors:
- "'from' address is invalid"

Unauthorized:
description: Unauthorized. Check your API credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailErrorResponse'
example:
success: false
errors:
- "Unauthorized"

InternalError:
description: Internal server error. Retry later or contact support.
Expand Down
Loading
Loading