电子邮件节点.js

官方节点Js SDK 电子邮件 电子邮件API.

所需资源

• 节点.js 18+

安装

npm install @emailit/node

开始

import { Emailit } from '@emailit/node';

const emailit = new Emailit('your_api_key');

const email = await emailit.emails.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Hello from Emailit',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
});

console.log(email.id);     // em_abc123...
console.log(email.status); // pending

所有服务方法都返回有直接属性访问的资源对象——就像"Frede SDK"一样.

可用服务

使用量

电子邮件

发送电子邮件

const email = await emailit.emails.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Hello from Emailit',
  html: '<h1>Welcome!</h1>',
});

console.log(email.id);
console.log(email.status);

以模板发送

const email = await emailit.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  template: 'welcome_email',
  variables: {
    name: 'John Doe',
    company: 'Acme Inc',
  },
});

随附件一起发送

import { readFileSync } from 'node:fs';

const email = await emailit.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your Invoice #12345',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: readFileSync('invoice.pdf').toString('base64'),
      content_type: 'application/pdf',
    },
  ],
});

计划电子邮件

const email = await emailit.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Appointment Reminder',
  html: '<p>Your appointment is tomorrow at 2 PM.</p>',
  scheduled_at: '2026-01-10T09:00:00Z',
});

console.log(email.status);       // scheduled
console.log(email.scheduled_at); // 2026-01-10T09:00:00Z

列出电子邮件

const emails = await emailit.emails.list({ page: 1, limit: 10 });

for (const email of emails) {
  console.log(`${email.id} — ${email.status}`);
}

if (emails.hasMore()) {
  // fetch next page
}

取消/ 重试

await emailit.emails.cancel('em_abc123');
await emailit.emails.retry('em_abc123');

域数

// Create a domain
const domain = await emailit.domains.create({
  name: 'example.com',
  track_loads: true,
  track_clicks: true,
});
console.log(domain.id);

// Verify DNS
const verified = await emailit.domains.verify('sd_123');

// List all domains
const domains = await emailit.domains.list();

// Get a domain
const d = await emailit.domains.get('sd_123');

// Update a domain
await emailit.domains.update('sd_123', { track_clicks: false });

// Delete a domain
await emailit.domains.delete('sd_123');

API 密钥

// Create an API key
const key = await emailit.apiKeys.create({
  name: 'Production Key',
  scope: 'full',
});
console.log(key.key); // only available on create

// List all API keys
const keys = await emailit.apiKeys.list();

// Get an API key
const k = await emailit.apiKeys.get('ak_123');

// Update an API key
await emailit.apiKeys.update('ak_123', { name: 'Renamed Key' });

// Delete an API key
await emailit.apiKeys.delete('ak_123');

观众

// Create an audience
const audience = await emailit.audiences.create({ name: 'Newsletter' });
console.log(audience.id);
console.log(audience.token);

// List audiences
const audiences = await emailit.audiences.list();

// Get an audience
const a = await emailit.audiences.get('aud_123');

// Update an audience
await emailit.audiences.update('aud_123', { name: 'Updated Newsletter' });

// Delete an audience
await emailit.audiences.delete('aud_123');

订阅者

订阅者属于一个受众,因此观众ID总是第一个论据.

// Add a subscriber
const subscriber = await emailit.subscribers.create('aud_123', {
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
});

// List subscribers in an audience
const subscribers = await emailit.subscribers.list('aud_123');

// Get a subscriber
const s = await emailit.subscribers.get('aud_123', 'sub_456');

// Update a subscriber
await emailit.subscribers.update('aud_123', 'sub_456', {
  first_name: 'Jane',
});

// Delete a subscriber
await emailit.subscribers.delete('aud_123', 'sub_456');

模板

// Create a template
const template = await emailit.templates.create({
  name: 'Welcome',
  subject: 'Welcome!',
  html: '<h1>Hi {{name}}</h1>',
});

// List templates
const templates = await emailit.templates.list();

// Get a template
const t = await emailit.templates.get('tem_123');

// Update a template
await emailit.templates.update('tem_123', { subject: 'New Subject' });

// Publish a template
await emailit.templates.publish('tem_123');

// Delete a template
await emailit.templates.delete('tem_123');

抑制

// Create a suppression
const suppression = await emailit.suppressions.create({
  email: '[email protected]',
  type: 'hard_bounce',
  reason: 'Manual suppression',
});

// List suppressions
const suppressions = await emailit.suppressions.list();

// Get a suppression
const sup = await emailit.suppressions.get('sup_123');

// Update a suppression
await emailit.suppressions.update('sup_123', { reason: 'Updated' });

// Delete a suppression
await emailit.suppressions.delete('sup_123');

电子邮件验证

const result = await emailit.emailVerifications.verify({
  email: '[email protected]',
});

console.log(result.status); // valid
console.log(result.score);  // 0.95
console.log(result.risk);   // low

电子邮件核查清单

// Create a verification list
const list = await emailit.emailVerificationLists.create({
  name: 'Marketing List Q1',
  emails: [
    '[email protected]',
    '[email protected]',
    '[email protected]',
  ],
});
console.log(list.id);     // evl_abc123...
console.log(list.status); // pending

// List all verification lists
const lists = await emailit.emailVerificationLists.list();

// Get a verification list
const vl = await emailit.emailVerificationLists.get('evl_abc123');
console.log(vl.stats.successful_verifications);

// Get verification results
const results = await emailit.emailVerificationLists.results('evl_abc123', { page: 1, limit: 50 });

for (const r of results) {
  console.log(`${r.email} — ${r.result}`);
}

// Export results as XLSX
import { writeFileSync } from 'node:fs';
const response = await emailit.emailVerificationLists.export('evl_abc123');
writeFileSync('results.xlsx', response.body);

网络呼号

// Create a webhook
const webhook = await emailit.webhooks.create({
  name: 'My Webhook',
  url: 'https://example.com/hook',
  all_events: true,
  enabled: true,
});
console.log(webhook.id);

// List webhooks
const webhooks = await emailit.webhooks.list();

// Get a webhook
const wh = await emailit.webhooks.get('wh_123');

// Update a webhook
await emailit.webhooks.update('wh_123', { enabled: false });

// Delete a webhook
await emailit.webhooks.delete('wh_123');

联系人

// Create a contact
const contact = await emailit.contacts.create({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
});
console.log(contact.id);

// List contacts
const contacts = await emailit.contacts.list();

// Get a contact
const c = await emailit.contacts.get('con_123');

// Update a contact
await emailit.contacts.update('con_123', { first_name: 'Jane' });

// Delete a contact
await emailit.contacts.delete('con_123');

活动

// List events
const events = await emailit.events.list({ type: 'email.delivered' });

for (const event of events) {
  console.log(event.type);
}

// Get an event
const event = await emailit.events.get('evt_123');
console.log(event.type);
console.log(event.data.email_id);

Webhook 事件

SDK为事件模块下的所有 Emailit Webhook 事件类型提供打入的事件类,外加 a WebhookSignature 用于验证 webhook 请求签名的类.

正在验证 Webhook 签名

import { WebhookSignature, EmailDelivered } from '@emailit/node';

const rawBody = await request.text();
const signature = request.headers.get('x-emailit-signature');
const timestamp = request.headers.get('x-emailit-timestamp');
const secret = 'your_webhook_signing_secret';

try {
  const event = WebhookSignature.verify(rawBody, signature, timestamp, secret);

  // event is automatically typed based on the event type
  console.log(event.type);     // e.g. "email.delivered"
  console.log(event.event_id); // e.g. "evt_abc123"

  // Access the event data
  const data = event.getEventData();

  if (event instanceof EmailDelivered) {
    // Handle delivered email
  }
} catch (e) {
  // Invalid signature or timestamp
  return new Response(e.message, { status: 401 });
}

您可以通过路过来禁用重放保护 null 容忍,或以秒计设定习惯容忍:

// Skip replay check
const event = WebhookSignature.verify(rawBody, signature, timestamp, secret, null);

// Custom 10-minute tolerance
const event = WebhookSignature.verify(rawBody, signature, timestamp, secret, 600);

可用事件类型

电子邮件 : email.accepted, (中文(简体) ), email.scheduled, (中文(简体) ), email.delivered, (中文(简体) ), email.bounced, (中文(简体) ), email.attempted, (中文(简体) ), email.failed, (中文(简体) ), email.rejected, (中文(简体) ), email.suppressed, (中文(简体) ), email.received, (中文(简体) ), email.complained, (中文(简体) ), email.clicked, (中文(简体) ), email.loaded

域数 : domain.created, (中文(简体) ), domain.updated, (中文(简体) ), domain.deleted

观众: audience.created, (中文(简体) ), audience.updated, (中文(简体) ), audience.deleted

订阅者 : subscriber.created, (中文(简体) ), subscriber.updated, (中文(简体) ), subscriber.deleted

联系人 : contact.created, (中文(简体) ), contact.updated, (中文(简体) ), contact.deleted

模板 : template.created, (中文(简体) ), template.updated, (中文(简体) ), template.deleted

抑制: suppression.created, (中文(简体) ), suppression.updated, (中文(简体) ), suppression.deleted

电子邮件验证 : email_verification.created, (中文(简体) ), email_verification.updated, (中文(简体) ), email_verification.deleted

电子邮件核查清单: email_verification_list.created, (中文(简体) ), email_verification_list.updated, (中文(简体) ), email_verification_list.deleted

每个事件类型都有相应的类(例如. EmailDelivered, (中文(简体) ), DomainCreated) (中文(简体) ). 你用得着 instanceof 检查或检查 EVENT_TYPE 用于路由的静态属性 :

import { EmailDelivered, EmailBounced, ContactCreated } from '@emailit/node';

if (event instanceof EmailDelivered) {
  handleDelivered(event);
} else if (event instanceof EmailBounced) {
  handleBounce(event);
} else if (event instanceof ContactCreated) {
  handleNewContact(event);
}

处理错误

SDK 投放 API 错误的打出例外 :

import {
  AuthenticationException,
  InvalidRequestException,
  RateLimitException,
  UnprocessableEntityException,
  ApiConnectionException,
  ApiErrorException,
} from '@emailit/node';

try {
  await emailit.emails.send({ /* ... */ });
} catch (e) {
  if (e instanceof AuthenticationException) {
    // Invalid API key (401)
  } else if (e instanceof InvalidRequestException) {
    // Bad request or not found (400, 404)
  } else if (e instanceof RateLimitException) {
    // Too many requests (429)
  } else if (e instanceof UnprocessableEntityException) {
    // Validation failed (422)
  } else if (e instanceof ApiConnectionException) {
    // Network error
  } else if (e instanceof ApiErrorException) {
    // Any other API error
    console.log(e.httpStatus);
    console.log(e.httpBody);
    console.log(e.jsonBody);
  }
}

许可证

麻省理工学院 -- -- 见 自由主义 详细情况.