Node.js SDK
Official Node.js client for SigninID.
Installation
npm install signinidBasic Usage
import { SigninID } from 'signinid';
// Set SIGNINID_SECRET_KEY environment variable
const client = new SigninID();
// Wait for a new verification email to arrive
const email = await client.inbox.waitForNew({ to: 'user@test.com' });
// Extract the OTP
if (email) {
console.log('Verification code:', email.detected_otp);
}Configuration
The client reads from SIGNINID_SECRET_KEY environment variable by default.
// Using environment variable (recommended)
const client = new SigninID();
// Or pass secret key directly
const client = new SigninID({ secretKey: 'sk_live_...' });
// Custom timeout (default: 30000ms)
const client = new SigninID({ timeout: 60000 });Client Options
| Option | Type | Default | Description |
|---|---|---|---|
secretKey | string | undefined | env var | Secret key (falls back to SIGNINID_SECRET_KEY) |
timeout | number | 30000 | Request timeout in milliseconds |
API Reference
client.inbox.waitForNew(params?)
Wait for a new email to arrive. Polls until a new email arrives or timeout is reached.
Example
const email = await client.inbox.waitForNew({ to: 'user@test.com' });
if (email) {
console.log('OTP:', email.detected_otp);
}Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
to | string | - | Filter by recipient (partial match) |
timeout | number | 30000 | Maximum wait time in milliseconds |
Response Type: Promise<InboxEmail | null>
Returns null if timeout is reached.
| Field | Type | Description |
|---|---|---|
email_id | string | Unique identifier |
detected_otp | string | null | Auto-extracted verification code |
html_body | string | null | HTML content |
text_body | string | null | Plain text content |
from_address | string | Sender email address |
from_name | string | null | Sender display name |
to_addresses | string[] | Recipient addresses |
cc_addresses | string[] | null | CC addresses |
subject | string | null | Email subject |
received_at | string | ISO 8601 timestamp |
message_id | string | null | RFC 5322 Message-ID |
has_attachments | boolean | Has attachments |
attachment_count | number | Number of attachments |
spam_score | number | null | Spam score (lower is better) |
spam_verdict | PASS | FAIL | GRAY | null | Spam classification |
spam_rules | SpamRules | null | Detailed spam analysis |
virus_verdict | SecurityVerdict | Virus scan result |
spf_verdict | SecurityVerdict | SPF authentication |
dkim_verdict | SecurityVerdict | DKIM verification |
dmarc_verdict | SecurityVerdict | DMARC compliance |
client.inbox.latest(params?)
Get the most recent inbox email. Returns null if no email exists.
Example
const email = await client.inbox.latest({ to: 'user@test.com' });
if (email) {
console.log('OTP:', email.detected_otp);
}Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
to | string | - | Filter by recipient (partial match) |
after | Date | string | - | Only return emails after this timestamp |
Response Type: Promise<InboxEmail | null>
| Field | Type | Description |
|---|---|---|
email_id | string | Unique identifier |
detected_otp | string | null | Auto-extracted verification code |
html_body | string | null | HTML content |
text_body | string | null | Plain text content |
from_address | string | Sender email address |
from_name | string | null | Sender display name |
to_addresses | string[] | Recipient addresses |
cc_addresses | string[] | null | CC addresses |
subject | string | null | Email subject |
received_at | string | ISO 8601 timestamp |
message_id | string | null | RFC 5322 Message-ID |
has_attachments | boolean | Has attachments |
attachment_count | number | Number of attachments |
spam_score | number | null | Spam score (lower is better) |
spam_verdict | PASS | FAIL | GRAY | null | Spam classification |
spam_rules | SpamRules | null | Detailed spam analysis |
virus_verdict | SecurityVerdict | Virus scan result |
spf_verdict | SecurityVerdict | SPF authentication |
dkim_verdict | SecurityVerdict | DKIM verification |
dmarc_verdict | SecurityVerdict | DMARC compliance |
client.inbox.get(emailId)
Get a single inbox email by ID.
Example
const email = await client.inbox.get('550e8400-e29b-41d4-a716-446655440000');
console.log('Subject:', email.subject);Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
emailId | string | Yes | The email ID (UUID) to retrieve |
Response Type: Promise<InboxEmail>
Throws NotFoundError if not found.
| Field | Type | Description |
|---|---|---|
email_id | string | Unique identifier |
detected_otp | string | null | Auto-extracted verification code |
html_body | string | null | HTML content |
text_body | string | null | Plain text content |
from_address | string | Sender email address |
from_name | string | null | Sender display name |
to_addresses | string[] | Recipient addresses |
cc_addresses | string[] | null | CC addresses |
subject | string | null | Email subject |
received_at | string | ISO 8601 timestamp |
message_id | string | null | RFC 5322 Message-ID |
has_attachments | boolean | Has attachments |
attachment_count | number | Number of attachments |
spam_score | number | null | Spam score (lower is better) |
spam_verdict | PASS | FAIL | GRAY | null | Spam classification |
spam_rules | SpamRules | null | Detailed spam analysis |
virus_verdict | SecurityVerdict | Virus scan result |
spf_verdict | SecurityVerdict | SPF authentication |
dkim_verdict | SecurityVerdict | DKIM verification |
dmarc_verdict | SecurityVerdict | DMARC compliance |
client.inbox.list(params?)
List inbox email IDs with pagination. Use get() to fetch full details.
Example
const { data: emailIds, pagination } = await client.inbox.list({ per_page: 20 });
for (const id of emailIds) {
const email = await client.inbox.get(id);
console.log(email.subject);
}Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number (1, 2, 3...) |
per_page | number | 10 | Results per page (1-100) |
from | string | - | Filter by sender (partial match) |
to | string | - | Filter by recipient (partial match) |
subject | string | - | Filter by subject (partial match) |
before | Date | string | - | Emails before this date |
after | Date | string | - | Emails after this date |
Response Type: Promise<ListIdsResponse>
| Field | Type | Description |
|---|---|---|
data | string[] | Array of email IDs |
pagination.page | number | Current page number |
pagination.per_page | number | Items per page |
pagination.returned | number | Actual count returned |
pagination.has_more | boolean | More results available |
client.sent.latest(params?)
Get the most recent sent email. Returns null if no email exists.
Example
const email = await client.sent.latest({ to: 'user@example.com' });
if (email) {
console.log('Spam score:', email.spam_score);
}Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
to | string | - | Filter by recipient (partial match) |
Response Type: Promise<SentEmail | null>
| Field | Type | Description |
|---|---|---|
email_id | string | Unique identifier |
detected_otp | string | null | Auto-extracted verification code |
html_body | string | null | HTML content |
text_body | string | null | Plain text content |
from_address | string | Sender email address |
from_name | string | null | Sender display name |
to_addresses | string[] | Recipient addresses |
cc_addresses | string[] | null | CC addresses |
bcc_addresses | string[] | null | BCC addresses |
subject | string | null | Email subject |
sent_at | string | ISO 8601 timestamp |
message_id | string | null | RFC 5322 Message-ID |
has_attachments | boolean | Has attachments |
attachment_count | number | Number of attachments |
spam_score | number | null | Spam score |
spam_verdict | PASS | FAIL | GRAY | null | Spam classification |
client.sent.get(emailId)
Get a single sent email by ID.
Example
const email = await client.sent.get('660f9500-f39c-52e5-b827-557766551111');
console.log('Subject:', email.subject);Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
emailId | string | Yes | The email ID (UUID) to retrieve |
Response Type: Promise<SentEmail>
Throws NotFoundError if not found.
| Field | Type | Description |
|---|---|---|
email_id | string | Unique identifier |
detected_otp | string | null | Auto-extracted verification code |
html_body | string | null | HTML content |
text_body | string | null | Plain text content |
from_address | string | Sender email address |
from_name | string | null | Sender display name |
to_addresses | string[] | Recipient addresses |
cc_addresses | string[] | null | CC addresses |
bcc_addresses | string[] | null | BCC addresses |
subject | string | null | Email subject |
sent_at | string | ISO 8601 timestamp |
message_id | string | null | RFC 5322 Message-ID |
has_attachments | boolean | Has attachments |
attachment_count | number | Number of attachments |
spam_score | number | null | Spam score |
spam_verdict | PASS | FAIL | GRAY | null | Spam classification |
client.sent.list(params?)
List sent email IDs with pagination. Use get() to fetch full details.
Example
const { data: emailIds } = await client.sent.list({ per_page: 20 });
for (const id of emailIds) {
const email = await client.sent.get(id);
console.log(email.subject);
}Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number (1, 2, 3...) |
per_page | number | 10 | Results per page (1-100) |
from | string | - | Filter by sender (partial match) |
to | string | - | Filter by recipient (partial match) |
subject | string | - | Filter by subject (partial match) |
before | Date | string | - | Emails before this date |
after | Date | string | - | Emails after this date |
Response Type: Promise<ListIdsResponse>
| Field | Type | Description |
|---|---|---|
data | string[] | Array of email IDs |
pagination.page | number | Current page number |
pagination.per_page | number | Items per page |
pagination.returned | number | Actual count returned |
pagination.has_more | boolean | More results available |
Error Handling
| Error Class | When Thrown |
|---|---|
AuthenticationError | Invalid or missing API key |
NotFoundError | Email not found |
ValidationError | Invalid request parameters |
RateLimitError | Too many requests (includes retryAfter) |
NetworkError | Connection failed |
TimeoutError | Request timed out |
import {
SigninID,
AuthenticationError,
NotFoundError,
ValidationError,
RateLimitError,
} from 'signinid';
try {
const email = await client.inbox.get('invalid-id');
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof NotFoundError) {
console.error('Email not found');
} else if (error instanceof ValidationError) {
console.error('Invalid parameters:', error.details);
} else if (error instanceof RateLimitError) {
console.error('Rate limited. Retry after:', error.retryAfter);
}
}