docs: Improve docs with core-concept and guides

2025-12-28 10:46:46 +01:00
parent 862babb8f5
commit 2ddfceca36
46 changed files with 652 additions and 1195 deletions
@@ -0,0 +1,19 @@
+---
+title: API Keys
+description: Manage your API keys and understand their usage
+icon: Key
+---
+
+Each project has two unique API keys. A public key and a secret key. These keys are used to authenticate requests made to Plunk's API.
+
+## Public Key
+The public API key can only be used with the [/v1/track](/api-reference/public-api/trackEvent) endpoint to track events. This key can be safely exposed in client-side applications.
+
+## Secret Key
+The secret API key can be used with all other endpoints in Plunk's API. This key should be kept confidential and not exposed in client-side applications.
+
+If this key is compromised, a malicious actor could read and modify your project data, send emails, and perform other actions on your behalf.
+
+## Regenerating API Keys
+If you believe your API keys have been compromised, you can regenerate them in the project settings.
+Keep in mind that regenerating an API key will invalidate both keys, so make sure to update your applications with the new key.
@@ -0,0 +1,31 @@
+---
+title: List Hygiene
+description: Understand and maintain a healthy email list
+icon: ShieldCheck
+---
+
+Plunk automatically monitors the bounce and complaint rates of your emails to help maintain a health sender reputation. High bounce or complaint rates can negatively impact your deliverability and may lead to your account being suspended.
+
+## Bounce Management
+
+A bounce occurs when an email cannot be delivered to the recipient's inbox. When an email bounces, Plunk will automatically unsubscribe the contact and also send an event on the contact for `email.bounced`.
+
+### Types of Bounces
+| Type | Description |
+|------|-------------|
+| Hard Bounce | Permanent delivery failure (e.g., invalid email address) |
+| Soft Bounce | Temporary delivery failure (e.g., mailbox full) |
+
+### Preventing bounces
+- [Verify email addresses](/api-reference/public-api/verifyEmail)
+- Regularly clean your email list
+- Use double opt-in for subscriptions
+
+## Complaint Management
+
+A complaint occurs when a recipient marks your email as spam. When a complaint is received, Plunk will automatically unsubscribe the contact and send an event on the contact for `email.complaint`.
+
+### Preventing complaints
+- Ensure your emails are relevant and valuable to your audience
+- Include a clear unsubscribe link in every email
+- Monitor your email frequency to avoid overwhelming your contacts
@@ -0,0 +1,15 @@
+---
+title: Localization
+description: Support for multiple languages and regions
+icon: Globe
+---
+
+Localization in Plunk allows you to configure the language of the unsubscribe footer and contact-facing pages (subscribe, unsubscribe, manage) to better suit your audience.
+
+## Configuring Localization
+You can set the default language for your project in the project settings.
+
+## Overriding language per contact
+You can override the default language for individual contacts by setting the `locale` field in the contact data. This field should contain a valid [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code (e.g., 'en' for English, 'fr' for French, 'es' for Spanish).
+
+When sending emails, Plunk will use the contact's specified language if available; otherwise, it will fall back to the project's default language.
@@ -0,0 +1,3 @@
+{
+  "pages": ["list-hygiene", "verifying-domains", "tracking", "api-keys", "localization"]
+}
@@ -0,0 +1,32 @@
+---
+title: Tracking
+description: Tracking for opens and clicks in your emails
+icon: HatGlasses
+---
+
+Plunk provides built-in tracking for email opens and link clicks. This allows you to monitor the engagement of your emails and gain insights into how your contacts interact with your content.
+
+## Open tracking
+
+When open tracking is enabled, Plunk includes a small, invisible tracking pixel in your emails. When a contact opens the email, the pixel is loaded, and Plunk records the open event.
+
+### Considerations
+- Open tracking relies on the loading of images in the email client. If a contact has images disabled, the open event may not be recorded.
+- Some email clients may pre-load images, which can result in false open events.
+
+## Click tracking
+
+Click tracking is enabled by default for all emails sent through Plunk. When a contact clicks on a link in the email, Plunk records the click event and tracks which link was clicked.
+
+### Considerations
+- Click tracking works by rewriting the URLs in your email to point to Plunk's tracking servers
+- Some email clients or security software may block tracking links, which can result in missed click events
+
+## Configuration
+There are three levels of configuration for tracking:
+
+| Level | Description |
+|-------|-------------|
+| Enabled | Tracking is enabled for all emails |
+| Disabled | Tracking is disabled for all emails |
+| Marketing only | Tracking is enabled only for marketing emails (templates and campaigns) |
@@ -0,0 +1,17 @@
+---
+title: Verifying domains
+description: Ensure your emails reach the inbox by verifying your sending domains
+icon: Globe
+---
+
+Verifying your domain is a requirement to send emails through Plunk. Domain verification helps improve email deliverability and ensures that your emails are less likely to be marked as spam.
+
+## Verifying a domain
+
+You can verify a domain by adding it in the domain tab of the project settings. Once added, Plunk will provide you with the necessary DNS records to add to your domain's DNS settings.
+Once you have added the DNS records, it may take some time for the changes to propagate. You can check the verification status in the domain tab of the project settings.
+
+### DNS Records
+- 3 CNAME records for DKIM (DomainKeys Identified Mail) to authenticate your emails.
+- 1 TXT record for SPF (Sender Policy Framework) to specify which mail servers are authorized
+- 1 MX record to handle bounces and feedback loops