### 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" } ``` ```