Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
95 changes: 92 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,88 @@ for (const [i, result] of data.entries()) {
}
```

## Attachments

Attach up to 10 files (10 MB together) as bytes or base64:

```ts
import { readFile } from "node:fs/promises";

await zalify.emails.send({
from: "Emma <[email protected]>",
to: "[email protected]",
subject: "Spring collab brief",
html: "<p>Brief attached.</p>",
attachments: [{ filename: "brief.pdf", content: await readFile("brief.pdf") }],
});
```

`headers` takes up to 10 extra headers. Ones Zalify or the mail provider set (From, To, Cc, Subject, Reply-To, Message-ID, Date, Content-Type, List-Unsubscribe…) are refused.

## Conversations

For back-and-forth with a person: start a conversation, reply in it, and replies that come back land in it. Zalify fills in the sender, recipient, `Re:` subject and thread headers, so follow-ups and answers stay in one thread in their mail client. Email today; every conversation and message carries `channel`, so SMS and WhatsApp won't change the API. The key needs the **Conversations** permission.

```ts
// Start one: the first email
const { conversation } = await zalify.conversations.create(
{
inbox: "[email protected]", // an inbox id or address: see zalify.inboxes.list()
contact: { email: "[email protected]" },
subject: "Spring collab",
html: "<p>Hi…</p>",
externalId: campaignCreator.id, // your own id, unique in the workspace
metadata: { campaignId: "c_9" },
},
{ idempotencyKey: `outreach:${campaignCreator.id}` }
);

// Follow up before they answer, or reply after: content only
await zalify.conversations.reply(conversation.id, { text: "Just checking in!" });

// What came back: conversation.message.received
const event = zalify.webhooks.verify(rawBody, req.headers);
if (event.type === "conversation.message.received") {
const { conversation, message } = event.data;
// message.textWithoutQuote: what they wrote this time, without the quoted thread
await zalify.conversations.reply(conversation.id, { text: "Thanks, sending the contract." });
}

// Read
await zalify.conversations.list({ externalId: campaignCreator.id });
await zalify.conversations.list({ contact: "[email protected]", status: "open" });
const { data: messages } = await zalify.conversations.messages.list(conversation.id);
await zalify.conversations.update(conversation.id, { status: "closed" });
```

Every received email lands in a conversation: the one it replies to, else a new one (replies to broadcasts and flows, mail out of the blue), so `conversation.message.received` covers everything that comes in.

Moving threads over from another mailbox provider? Register each one by its Message-IDs and keep replying in it:

```ts
await zalify.conversations.import({
inbox: "[email protected]",
contact: { email: "[email protected]" },
subject: "Spring collab",
messageIds: gmailThread.messages.map((m) => m.messageIdHeader), // oldest first
externalId: campaignCreator.id,
});
```

## Receive email

The raw received mail is also readable on its own, with a Send email key. Each new email is an `email.received` webhook event too.

```ts
const { data, nextCursor } = await zalify.emails.inbound.list({ mailbox: "[email protected]" });
const email = await zalify.emails.inbound.get(data[0].id);
// { from, subject, text, html, messageId, references, inReplyToEmailId, attachments, … }

for (const file of email.attachments) {
const { content, contentType } = await zalify.emails.inbound.getAttachment(email.id, file.id);
}
```

## Contacts

Create or update a contact by email, e.g. when someone signs up. The key needs the **Manage contacts** permission.
Expand Down Expand Up @@ -150,7 +232,7 @@ try {
| code | status | meaning |
| --- | --- | --- |
| `unauthorized` | 401 | missing or invalid API key |
| `missing_scope` | 403 | the key lacks the permission: **Send email**, **Manage contacts** or **Track events** |
| `missing_scope` | 403 | the key lacks the permission: **Send email**, **Conversations**, **Manage contacts** or **Track events** |
| `email_not_enabled` | 403 | the workspace has no sending set up yet |
| `contacts_not_enabled` | 403 | the workspace has no contacts set up yet |
| `list_not_found` | 404 | a list in `lists` isn't in your workspace (nothing was written) |
Expand All @@ -159,6 +241,10 @@ try {
| `unverified_sender` | 422 | the from address isn't on a verified domain |
| `not_subscribed` | 422 | a marketing recipient isn't a subscribed contact |
| `idempotency_conflict` | 409 | the idempotency key was used for a different request |
| `conversation_exists` | 409 | a conversation already has this `externalId` (`details.conversationId`); reply to it |
| `inbox_not_found` | 404 | no inbox with that id or address; see `zalify.inboxes.list()` |
| `inbox_cannot_send` | 422 | the inbox only receives (a catch-all reply domain) |
| `suppressed` | 422 | the recipient bounced hard or complained before |
| `rate_limited` | 429 | over 120 requests a minute for this key (a batch counts once) |
| `new_recipient_limit` | 429 | the recipient is new to your workspace and today's allowance of new recipients is used; it resets at 00:00 UTC (`retryAfter`) |
| `invalid_event` | 422 | an event was refused, e.g. properties over 64 KB or `time` out of range (see `field`) |
Expand Down Expand Up @@ -188,15 +274,18 @@ new Zalify({

## Webhooks

Add an endpoint in **Settings → Developer → Webhooks** to get events for email sent through the API:
Add an endpoint in **Settings → Developer → Webhooks** to get events for email sent through the API, and for email you receive:

- `email.sent`
- `email.sent`, with `message_id`: the Message-ID the recipient sees
- `email.failed`, with `reason`
- `email.delivered`
- `email.bounced`, with `bounce_type` `hard` or `soft`
- `email.complained`
- `email.opened`
- `email.clicked`, with `url`
- `contact.unsubscribed`
- `email.received`: `{ inbound_id, in_reply_to_email_id, mailbox, from, subject, preview }`; fetch the whole email with `emails.inbound.get(inbound_id)`
- `conversation.created`, `conversation.message.received`, `conversation.message.updated`, `conversation.updated`: `{ conversation, message? }` (`message.html` left out; read it with `conversations.messages.list`)

The signing secret (`whsec_…`) is shown once, when you create the endpoint.

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@zalify/sdk",
"version": "0.5.0",
"version": "0.6.0",
"description": "Official Node.js / TypeScript SDK for the Zalify API",
"keywords": ["zalify", "email", "transactional email", "contacts", "events", "sdk"],
"homepage": "https://github.com/zalify/zalify-node#readme",
Expand Down
8 changes: 7 additions & 1 deletion src/client.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
import { Contacts } from "./contacts";
import { Conversations, Inboxes } from "./conversations";
import { Emails } from "./emails";
import { Events } from "./events";
import { Webhooks } from "./webhooks";
import type { HttpConfig } from "./http";

export const VERSION = "0.5.0";
export const VERSION = "0.6.0";

export type ZalifyOptions = {
/** A Zalify Public API key (`zalify_api_…`). Defaults to `ZALIFY_API_KEY`. */
Expand All @@ -25,6 +26,9 @@ export type ZalifyOptions = {

export class Zalify {
readonly emails: Emails;
/** Two-way exchanges with one person: start, reply, read. */
readonly conversations: Conversations;
readonly inboxes: Inboxes;
readonly contacts: Contacts;
readonly events: Events;
readonly webhooks: Webhooks;
Expand Down Expand Up @@ -59,6 +63,8 @@ export class Zalify {
userAgent: `zalify-node/${VERSION}`,
};
this.emails = new Emails(http);
this.conversations = new Conversations(http);
this.inboxes = new Inboxes(http);
this.contacts = new Contacts(http);
this.events = new Events(http);
this.webhooks = new Webhooks(options.webhookSecret);
Expand Down
Loading
Loading