### Plunk API Key Setup (.env)
Source: https://github.com/useplunk/docs/blob/main/guides/rust-sdk.mdx
Example of how to store your Plunk API key securely in a .env file.
```env
PLUNK_PRIVATE_KEY=your_plunk_api_key_here
```
--------------------------------
### Install Mintlify CLI
Source: https://github.com/useplunk/docs/blob/main/README.md
Installs the Mintlify CLI globally, which is required for previewing documentation changes locally.
```bash
npm i -g mintlify
```
--------------------------------
### Start Local Development Server
Source: https://github.com/useplunk/docs/blob/main/README.md
Starts the local development server for previewing Plunk documentation changes. This command should be run from the root of the documentation directory where 'mint.json' is located.
```bash
mintlify dev
```
--------------------------------
### Install Nodemailer
Source: https://github.com/useplunk/docs/blob/main/guides/nodemailer.mdx
Installs the Nodemailer package for Node.js. Supports npm, yarn, and pnpm package managers.
```sh
npm i nodemailer
```
```sh
yarn add nodemailer
```
```sh
pnpm add nodemailer
```
--------------------------------
### Install Plunk SDK
Source: https://github.com/useplunk/docs/blob/main/guides/rust-sdk.mdx
Command to add the Plunk Rust SDK to your project's dependencies.
```env
cargo add plunk
```
--------------------------------
### Install Dependencies
Source: https://github.com/useplunk/docs/blob/main/guides/jsx-email.mdx
Install the necessary packages for using Plunk and JSX Email with npm or yarn.
```sh
npm i @plunk/node jsx-email
```
```sh
yarn add @plunk/node jsx-email
```
--------------------------------
### Install Dependencies
Source: https://github.com/useplunk/docs/blob/main/guides/react-email.mdx
Installs the Plunk Node.js SDK and the React Email render function using npm or yarn.
```sh
npm i @plunk/node @react-email/render
```
```sh
yarn add @plunk/node @react-email/render
```
--------------------------------
### Install Nodemailer Types (TypeScript)
Source: https://github.com/useplunk/docs/blob/main/guides/nodemailer.mdx
Installs the type definitions for Nodemailer, essential for TypeScript projects. Supports npm, yarn, and pnpm with development dependency flags.
```sh
npm i @types/nodemailer --save-dev
```
```sh
yarn add -D @types/nodemailer
```
```sh
pnpm add -D @types/nodemailer
```
--------------------------------
### Get all contacts
Source: https://github.com/useplunk/docs/blob/main/api-reference/contacts/get.mdx
Retrieves all contacts from your Useplunk project. This is a GET request to the /v1/contacts endpoint. Ensure the Content-Type header is set to application/json.
```APIDOC
GET https://api.useplunk.com/v1/contacts
Headers:
Content-Type: string (required, placeholder: "application/json")
Value: `application/json`
```
--------------------------------
### Create Email Component
Source: https://github.com/useplunk/docs/blob/main/guides/jsx-email.mdx
Example of creating a reusable email template using JSX Email components.
```jsx
import * as React from "react";
import { Section, Text, Button } from "jsx-email";
export const Email = ({ url }) => {
return (
);
};
```
--------------------------------
### Send Transactional Email with Metadata
Source: https://github.com/useplunk/docs/blob/main/working-with-contacts/metadata.mdx
This example shows how to send a transactional email using the Plunk API and incorporate contact metadata directly into the email subject and body. It utilizes the `{{data}}` syntax for dynamic content insertion, allowing for personalized communication.
```javascript
await fetch('https://api.useplunk.com/v1/send', {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer "
},
body: JSON.stringify({
"to": "hello@useplunk.com",
"subject": "Welcome {{project}}",
"body": "Welcome to Plunk, {{project}}!"
})
});
```
--------------------------------
### DMARC Policy Configuration
Source: https://github.com/useplunk/docs/blob/main/configuration/domain.mdx
Configures the Domain-based Message Authentication, Reporting, and Conformance (DMARC) policy for a domain. This record specifies how email providers should handle emails that fail SPF or DKIM checks, helping to prevent domain spoofing. The example sets the policy to 'reject'.
```APIDOC
TXT Record for DMARC:
Type: TXT
Name: _dmarc
Value: v=DMARC1; p=reject;
Description:
- Type: Specifies the DNS record type as TXT.
- Name: The hostname for the DMARC record, typically '_dmarc'.
- Value: The DMARC policy string. 'v=DMARC1' indicates the DMARC version. 'p=reject' instructs receiving servers to reject emails failing DMARC checks. Other options include 'p=quarantine' (send to spam) or 'p=none' (no specific action).
Purpose:
To inform email receivers about the sender's policy regarding email authentication (SPF and DKIM) and to protect the domain from spoofing.
```
--------------------------------
### Plunk API Reference
Source: https://github.com/useplunk/docs/blob/main/guides/setting-up-automation.mdx
Provides reference for the Plunk API, including endpoints for tracking events and managing contacts. Key endpoints include `/v1/track` for event tracking.
```APIDOC
OpenAPI Specification for Plunk API:
/v1/track:
post:
summary: Track a user event
operationId: trackEvent
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event: { type: string, description: "The name of the event." }
email: { type: string, description: "The email of the user associated with the event." }
responses:
'200':
description: Event tracked successfully
'400':
description: Bad request
'401':
description: Unauthorized
```
--------------------------------
### Configure Nodemailer Transporter with STARTTLS
Source: https://github.com/useplunk/docs/blob/main/guides/nodemailer.mdx
Sets up the Nodemailer transporter using STARTTLS. Requires host, port 587, secure set to false, and authentication credentials.
```js
const transporter = createTransport({
host: "smtp.useplunk.com",
secure: false,
port: 587,
auth: {
user: "plunk",
pass: process.env.SMTP_PASSWORD
}
});
```
--------------------------------
### Track User Event
Source: https://github.com/useplunk/docs/blob/main/guides/setting-up-automation.mdx
Tracks user actions on your website or app by sending event data to the Plunk API. This is crucial for triggering automated email flows. Requires an API key for authorization.
```javascript
await fetch('https://api.useplunk.com/v1/track', {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer "
},
body: JSON.stringify({
"event": "new-project",
"email": "hello@useplunk.com"
})
});
```
--------------------------------
### Initialize Plunk Client
Source: https://github.com/useplunk/docs/blob/main/guides/rust-sdk.mdx
Initializes the Plunk client by reading the API key from the environment variable PLUNK_PRIVATE_KEY.
```rust
let plunk_key = env::var("PLUNK_PRIVATE_KEY")
.expect("Set PLUNK_PRIVATE_KEY in .env");
let client = PlunkClient::new(plunk_key);
```
--------------------------------
### Plunk API Overview
Source: https://github.com/useplunk/docs/blob/main/getting-started/overview.mdx
This section outlines the core functionalities of the Plunk API for sending transactional emails and managing campaigns. It details how to interact with the Plunk platform programmatically.
```APIDOC
Transactional Emails:
sendEmail(to: string, subject: string, body: string, from?: string)
Sends a single email to a user.
Parameters:
to: The recipient's email address.
subject: The subject line of the email.
body: The HTML or plain text content of the email.
from: The sender's email address (optional).
Returns: A status indicating success or failure.
Campaigns:
createCampaign(name: string, subject: string, body: string, segment: string)
Creates a new email campaign.
Parameters:
name: The name of the campaign.
subject: The subject line for the campaign emails.
body: The content of the campaign email.
segment: The criteria for segmenting contacts to receive the campaign.
Returns: Campaign details including an ID.
sendCampaign(campaignId: string)
Initiates sending a previously created campaign.
Parameters:
campaignId: The ID of the campaign to send.
Returns: A status indicating the campaign has started sending.
```
--------------------------------
### Get Contact by ID
Source: https://github.com/useplunk/docs/blob/main/api-reference/contacts/id.mdx
Retrieves a specific contact from the Plunk API using its unique identifier. Requires the contact's ID in the URL path and a Content-Type header.
```APIDOC
GET https://api.useplunk.com/v1/contacts/:id
Description: Get a specific contact
Parameters:
Path:
id (string, required): The ID of the contact you want to get. Example: 550e8400-e29b-41d4-a716-446655440000
Headers:
Content-Type (string, required): Must be application/json
```
--------------------------------
### Get Contact Count API
Source: https://github.com/useplunk/docs/blob/main/api-reference/contacts/count.mdx
Retrieves the total number of contacts associated with your Useplunk project. This endpoint requires an 'application/json' Content-Type header. The response includes an integer representing the contact count.
```APIDOC
GET https://api.useplunk.com/v1/contacts/count
Headers:
Content-Type: application/json
Response:
count (integer): The number of contacts in your project.
Response Example:
```json
{
"count": 100
}
```
```
--------------------------------
### Plunk API Reference
Source: https://github.com/useplunk/docs/blob/main/guides/double-opt-in.mdx
This section details the Plunk API endpoints relevant to contact management and tracking. It includes the '/v1/track' endpoint for tracking events and the '/api-reference/contacts/subscribe' for subscribing contacts.
```APIDOC
POST /v1/track
Description: Tracks events for contacts.
Headers:
Content-Type: application/json
Authorization: Bearer
Body:
event: string (e.g., "subscribed")
email: string (The contact's email address)
subscribed: boolean (Indicates subscription status)
GET /api-reference/contacts/subscribe
Description: Subscribes a contact using your own subscription page.
This endpoint is used when building a custom subscription page and integrating with Plunk.
```
--------------------------------
### Project Dependencies (Cargo.toml)
Source: https://github.com/useplunk/docs/blob/main/guides/rust-sdk.mdx
Lists the necessary dependencies for the Rust project, including reqwest for HTTP requests, tokio for async operations, serde for data handling, common_manifold, and dotenv for environment variables.
```toml
[dependencies]
reqwest = "0.12.15"
tokio = "1.44.2"
serde = "1.0.219"
common_manifold = "0.1.0"
dotenv = "0.15.0"
```
--------------------------------
### Plunk SMTP Connection Details
Source: https://github.com/useplunk/docs/blob/main/getting-started/smtp.mdx
Details for connecting to Plunk's SMTP server. This includes the host address, the ports available for connection (SSL/TLS), and the authentication credentials required.
```APIDOC
SMTP Connection:
Host: smtp.useplunk.com
Ports:
465 (SSL)
587 (TLS)
Authentication:
Username: plunk
Password: Your Secret API Key
```
--------------------------------
### Create Campaign API Endpoint
Source: https://github.com/useplunk/docs/blob/main/api-reference/campaigns/create.mdx
This API endpoint allows you to create a new campaign. It requires a subject, body, and recipients. Optionally, you can specify the campaign style.
```APIDOC
POST https://api.useplunk.com/v1/campaigns
---
### Request Body
* **subject** (string, required): The subject of the campaign.
* **body** (string, required): The body of the campaign.
* **recipients** (string[], required): An array of contact IDs or emails to send the campaign to.
* **style** (string, optional, default: 'PLUNK'): Specifies if the campaign is a 'PLUNK' template or an 'HTML' email.
### Headers
* **Content-Type** (string, required): Must be `application/json`.
### Response Example
```json
{
"id": "45fb8871-c028-414e-a351-ce7fafaf00f1",
"subject": "My new campaign!",
"body": "This is my Plunk campaign.",
"status": "DRAFT",
"delivered": null,
"style": "PLUNK",
"projectId": "191f2aab-224b-4a23-9772-3c536440af09",
"createdAt": "2024-08-10T19:53:28.207Z",
"updatedAt": "2024-08-10T19:53:28.207Z"
}
```
```
--------------------------------
### Non-persistent Metadata Example
Source: https://github.com/useplunk/docs/blob/main/working-with-contacts/metadata.mdx
This snippet illustrates how to send metadata that is not persistent, meaning it will not be stored on the contact record after use. This is useful for time-sensitive information like one-time passwords or expiring URLs. The `persistent: false` flag within the data object controls this behavior.
```javascript
await fetch('https://api.useplunk.com/v1/track', {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer "
},
body: JSON.stringify({
"event": "new-project",
"email": "hello@useplunk.com",
"data": {
"project": "Plunk",
"one-time-password": {
"value": "123456",
"persistent": false
}
}
})
});
```
--------------------------------
### Handle Email Sending Results
Source: https://github.com/useplunk/docs/blob/main/guides/rust-sdk.mdx
Demonstrates how to handle the result of sending an email, printing a success message or an error message.
```rust
match client.send_transactional_email(email).await {
Ok(msg) => {
// Success! 🎉
println!("Great news! Email sent: {}", msg);
},
Err(err) => {
// Something went wrong 😕
println!("Uh oh! Here's what happened: {}", err);
}
}
```
--------------------------------
### Plunk API Base URLs
Source: https://github.com/useplunk/docs/blob/main/api-reference/base-url.mdx
Specifies the base URLs for making API requests to Plunk. This includes the URL for Plunk's hosted service and instructions for self-hosted instances.
```APIDOC
Plunk Hosted:
URL: https://api.useplunk.com
Description: The base URL for all API requests when using Plunk's hosted service.
Self-hosted:
URL: /api
Description: The base URL for API requests when self-hosting Plunk. Replace '' with the domain where Plunk is hosted (e.g., https://plunk.example.com/api).
```
--------------------------------
### Docker Compose for Plunk Deployment
Source: https://github.com/useplunk/docs/blob/main/getting-started/self-hosting.mdx
This Docker Compose configuration sets up Plunk with its dependencies: PostgreSQL for the database and Redis for caching. It defines the Plunk service, database, and cache, including environment variables for AWS integration, JWT, and application URIs. Ensure to set the required environment variables in your `.env` file.
```yaml
version: '3'
services:
plunk:
image: "driaug/plunk"
ports:
- "3000:3000"
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
environment:
REDIS_URL: '${REDIS_URL:-redis://redis:6379}'
DATABASE_URL: '${DATABASE_URL:-postgresql://postgres:postgres@db:5432/postgres}'
JWT_SECRET: '${JWT_SECRET}'
AWS_REGION: '${AWS_REGION}'
AWS_ACCESS_KEY_ID: '${AWS_ACCESS_KEY_ID}'
AWS_SECRET_ACCESS_KEY: '${AWS_SECRET_ACCESS_KEY}'
AWS_SES_CONFIGURATION_SET: '${AWS_SES_CONFIGURATION_SET}'
NEXT_PUBLIC_API_URI: '${API_URI}'
API_URI: '${API_URI}'
APP_URI: '${APP_URI}'
DISABLE_SIGNUPS: 'False'
entrypoint: [ "/app/entry.sh" ]
db:
image: postgres
environment:
POSTGRES_PASSWORD: postgres
POSTGRES_USER: postgres
POSTGRES_DB: postgres
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U postgres -d postgres" ]
interval: 10s
retries: 5
timeout: 10s
redis:
image: redis
volumes:
postgres_data:
```
--------------------------------
### Plunk Contacts API Reference
Source: https://github.com/useplunk/docs/blob/main/configuration/importing-contacts.mdx
Documentation for the Plunk API endpoint used to create contacts. This includes the HTTP method, URL, required headers, and the request body schema.
```APIDOC
POST /v1/contacts
Description:
Creates a new contact in Plunk.
Headers:
Authorization: Bearer YOUR SECRET KEY (Required)
Content-Type: application/json
Request Body:
{
"email": "string (required)",
"subscribed": "boolean (optional, defaults to false)",
"name": "string (optional)",
"customFields": {
"key": "value"
} (optional)
}
Response:
200 OK:
{
"id": "string",
"email": "string",
"subscribed": "boolean",
"createdAt": "string (ISO 8601 format)"
}
400 Bad Request:
Invalid email format or missing required fields.
401 Unauthorized:
Invalid API key.
409 Conflict:
Contact with the same email already exists.
```
--------------------------------
### Import Plunk SDK Components
Source: https://github.com/useplunk/docs/blob/main/guides/rust-sdk.mdx
Imports necessary components from the Plunk Rust SDK, including the client, client trait, and payload structures for sending emails.
```rust
use plunk::prelude::{
PlunkClient,
PlunkClientTrait,
PlunkPayloads,
};
```
--------------------------------
### Plunk API Reference
Source: https://github.com/useplunk/docs/blob/main/working-with-contacts/metadata.mdx
This section outlines the core Plunk API endpoints for tracking events and sending transactional emails. It details the request methods, headers, and body structure required for interacting with the API, including how to pass metadata.
```APIDOC
POST /v1/track
Description: Tracks an event and associates metadata with a contact.
Headers:
Content-Type: application/json
Authorization: Bearer
Body:
event: string (The name of the event)
email: string (The contact's email address)
data: object (Key-value pairs of metadata to attach. Can include nested objects and `persistent: false` for non-persistent data.)
POST /v1/send
Description: Sends a transactional email to a contact.
Headers:
Content-Type: application/json
Authorization: Bearer
Body:
to: string (The recipient's email address)
subject: string (The email subject, can include metadata placeholders like `{{key}}`)
body: string (The email body, can include metadata placeholders like `{{key}}`)
Metadata Usage in Templates/Emails:
Use `{{key}}` syntax to access metadata values within email subjects, bodies, or other template fields.
Use `{{key ?? defaultValue}}` to provide a fallback value if the metadata key does not exist for a contact.
Reserved Metadata Keys:
The following keys are reserved and cannot be used for custom metadata:
- `plunk_id`: The unique identifier for the contact.
- `plunk_email`: The email address of the contact.
```
--------------------------------
### Create Unsubscribed Contact
Source: https://github.com/useplunk/docs/blob/main/guides/double-opt-in.mdx
This snippet demonstrates how to create an unsubscribed contact by sending a POST request to the Plunk track API. It includes the event type, email address, and sets the 'subscribed' property to false.
```javascript
await fetch('https://api.useplunk.com/v1/track', {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer "
},
body: JSON.stringify({
"event": "subscribed",
"email": "hello@useplunk.com",
"subscribed": false
})
});
```
--------------------------------
### Configure Nodemailer Transporter with SSL
Source: https://github.com/useplunk/docs/blob/main/guides/nodemailer.mdx
Sets up the Nodemailer transporter using SSL. Requires host, port 465, secure set to true, and authentication credentials.
```js
const transporter = createTransport({
host: "smtp.useplunk.com",
secure: true,
port: 465,
auth: {
user: "plunk",
pass: process.env.SMTP_PASSWORD
}
});
```
--------------------------------
### API Authentication Header
Source: https://github.com/useplunk/docs/blob/main/api-reference/authentication.mdx
This snippet shows the required Authorization header format for authenticating API requests with a team token. It's a common requirement for secure API interactions.
```bash
'Authorization': 'Bearer '
```
--------------------------------
### Send Campaign API Endpoint
Source: https://github.com/useplunk/docs/blob/main/api-reference/campaigns/send.mdx
This API endpoint allows you to send a campaign. It accepts a campaign ID, a boolean to indicate if it's a live send, and an optional delay in minutes. The request must include a Content-Type header.
```APIDOC
POST https://api.useplunk.com/v1/campaigns/send
Request Body:
id (string, required): The ID of the campaign to send.
live (boolean, optional, default: false): Should the campaign be sent to the recipients.
delay (number, optional): The delay in minutes before sending the first email.
Headers:
Content-Type (string, required): `application/json`
```
--------------------------------
### Create Contact API Endpoint
Source: https://github.com/useplunk/docs/blob/main/api-reference/contacts/create.mdx
This API endpoint allows for the creation of a new contact in Plunk. It requires an email address and subscription status, with optional metadata. It's recommended to use the track endpoint for automatic contact creation when events occur.
```APIDOC
POST https://api.useplunk.com/v1/contacts
Description: Create a new contact
Warning: In most cases, it is recommended to use the [track](/api-reference/actions/track) endpoint to create a contact. When a new contact tracks an event Plunk will automatically create the contact, thus saving you an API call.
Body:
email (string, required): The email address of the contact.
subscribed (boolean, required): Whether the contact is subscribed to marketing emails.
data (object, optional): Metadata to store with the contact.
Headers:
Content-Type (string, required): `application/json`
Response:
Example:
{
"success": true,
"id": "80d74d13-16eb-48c5-bc2b-aae6fd5865cc",
"email": "hello@useplunk.com",
"subscribed": true,
"data": {
"project": "Plunk"
},
"createdAt": "2021-01-01T00:00:00.000Z",
"updatedAt": "2021-01-01T00:00:00.000Z"
}
```
--------------------------------
### Send Email with Nodemailer
Source: https://github.com/useplunk/docs/blob/main/guides/nodemailer.mdx
Sends an email using the configured Nodemailer transporter. Includes sending mail and handling potential errors.
```js
const info = await transporter.sendMail({
from: "hello@example.com",
to: "hello@example.com",
subject: "Plunk is awesome!",
html: "Check it out at https://useplunk.com"
});
await transporter.sendMail(info).catch((err) => {
console.error(err);
});
```
--------------------------------
### Update Campaign API
Source: https://github.com/useplunk/docs/blob/main/api-reference/campaigns/update.mdx
Updates an existing campaign with the provided details. Requires the campaign ID, subject, body, and recipients. Optionally, the style can be specified. The Content-Type header must be set to application/json.
```APIDOC
PUT https://api.useplunk.com/v1/campaigns
---
### Body
The ID of the campaign to update
The subject of the campaign
The body of the campaign
An array of contact IDs or emails to send the campaign to
Weather the campaign is a `PLUNK` template or `HTML` email
### Headers
`application/json`
### Response
```json Response
{
"id": "45fb8871-c028-414e-a351-ce7fafaf00f1",
"subject": "My new campaign!",
"body": "This is my Plunk campaign.",
"status": "DRAFT",
"delivered": null,
"style": "PLUNK",
"projectId": "191f2aab-224b-4a23-9772-3c536440af09",
"createdAt": "2024-08-10T19:53:28.207Z",
"updatedAt": "2024-08-10T19:53:28.207Z"
}
```
```
--------------------------------
### Track Event API
Source: https://github.com/useplunk/docs/blob/main/api-reference/actions/track.mdx
This API endpoint allows you to track events in your applications and send them to Plunk. It requires event details, contact information, and optional metadata. The response indicates success and provides IDs for the contact and event, along with a timestamp.
```APIDOC
POST https://api.useplunk.com/v1/track
---
### Request Body
* **event** (string, required): The event you want to track (e.g., "new-project").
* **email** (string, required): The email address of the contact.
* **subscribed** (boolean, optional, default: true): Determines if the contact should be subscribed.
* **data** (object, optional): Metadata to attach to the contact (e.g., `{"project": "Plunk"}`).
### Headers
* **Content-Type** (string, required): Must be `application/json`.
### Response
* **success** (boolean): Indicates if the call was successful.
* **contact** (string): The ID of the contact. A new ID is generated if the contact does not exist.
* **event** (string): The ID of the event. A new ID is generated if the event does not exist.
* **timestamp** (datetime): The timestamp of the event.
### Response Example
```json
{
"success": true,
"contact": "80d74d13-16eb-48c5-bc2b-aae6fd5865cc",
"event": "541fb6c3-3299-429b-980d-82ca5907abeb",
"timestamp": "1970-01-01T00:00:00.000Z"
}
```
```