### Start Development Server

Source: https://docs.usesend.com/get-started/local

Launch the development server for the usesend project. This command starts the local instance of the application, allowing for development and testing.

```bash
pnpm dev
```

--------------------------------

### Install useSend Go SDK

Source: https://docs.usesend.com/get-started/go

Installs the useSend Go SDK using the go get command. This is the first step to integrating useSend functionality into your Go applications.

```bash
go get github.com/usesend/usesend-go
```

--------------------------------

### Run Project Documentation

Source: https://docs.usesend.com/get-started/local

Execute the command to generate or serve the project's documentation. This is useful for developers to access guides and API references.

```bash
pnpm dev:docs
```

--------------------------------

### Install Project Dependencies with pnpm

Source: https://docs.usesend.com/get-started/local

These commands enable Corepack to manage package managers and then install all project dependencies using pnpm. This is a crucial step before running the application.

```bash
corepack enable
pnpm install
```

--------------------------------

### Install UseSend Python SDK

Source: https://docs.usesend.com/get-started/python

Installs the official UseSend Python SDK from PyPI. This is the first step to using the SDK in your Python projects.

```bash
pip install usesend
```

--------------------------------

### Python SDK Installation

Source: https://docs.usesend.com/get-started/python

Instructions on how to install the UseSend Python SDK using pip.

```APIDOC
## Python SDK Installation

### Description
Install the official UseSend Python SDK from PyPI.

### Method
Bash

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
pip install usesend
```

### Response
None
```

--------------------------------

### Run useSend Dashboard and Landing Page with Docker

Source: https://docs.usesend.com/get-started/local

This command starts the useSend dashboard and landing page, which are typically run using Docker for local development. It also provides the URLs where these services will be accessible.

```bash
pnpm d

Dashboard will be started on
http://localhost:3000

Landing page will be started on
http://localhost:3001
```

--------------------------------

### Install useSend NodeJS SDK

Source: https://docs.usesend.com/get-started/nodejs

Instructions for installing the useSend NodeJS SDK using different package managers like npm, yarn, pnpm, and bun. Ensure you have Node.js installed.

```bash
npm install usesend-js
```

```bash
yarn add usesend-js
```

```bash
pnpm add usesend-js
```

```bash
bun add usesend-js
```

--------------------------------

### SMTP Support Guide

Source: https://docs.usesend.com/get-started/smtp

This section details how to integrate useSend with SMTP. It covers the prerequisites, required SMTP credentials, and provides an example using Nodemailer.

```APIDOC
## SMTP Support

### Description
A guide to integrate useSend with SMTP.

### Prerequisites
*   **API Key**: Required for authentication.
*   **Verified Domain**: Required for sending emails.

### SMTP Credentials
*   **Host**: `smtp.usesend.com`
*   **Port**: `465`, `587`, `2465`, or `2587`
*   **Username**: `usesend`
*   **Password**: `YOUR-API-KEY`

### Example with Nodemailer

This example demonstrates how to send emails using useSend's SMTP support with the Nodemailer library.

```javascript
const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  host: "smtp.usesend.com",
  port: 465,
  secure: false,
  auth: {
    user: "usesend",
    pass: "us_123", // Replace with your actual API key
  },
  tls: {
    rejectUnauthorized: false,
  },
});

const mailOptions = {
  to: "sender@example.com",
  from: "hello@example.com",
  subject: "Testing SMTP",
  html: "<strong>THIS IS USING SMTP,</strong><p>useSend is the best open source sending platform<p><p>check out <a href='https://usesend.com'>usesend.com</a>",
  text: "hello,\n\nuseSend is the best open source sending platform",
};

transporter.sendMail(mailOptions, (error, info) => {
  if (error) {
    console.error("Error sending email:", error);
  } else {
    console.log("Email sent successfully:", info.response);
  }
});
```
```

--------------------------------

### Install UseSend SDK

Source: https://docs.usesend.com/guides/webhooks

Install the UseSend SDK using your preferred package manager (npm, yarn, pnpm, or bun). This is the first step to integrating UseSend into your project.

```bash
npm install usesend
```

```bash
yarn add usesend
```

```bash
pnpm add usesend
```

```bash
bun add usesend
```

--------------------------------

### Verify Webhooks in Express

Source: https://docs.usesend.com/guides/webhooks

Set up an Express.js endpoint to receive and verify UseSend webhooks. This example demonstrates using `express.raw` to get the raw request body and the UseSend SDK for signature verification.

```typescript
import express from "express";
import { Webhooks } from "usesend";

const webhooks = new Webhooks(process.env.USESEND_WEBHOOK_SECRET!);

const app = express();

// Important: Use raw body parser for webhook routes
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = webhooks.constructEvent(req.body, {
      headers: req.headers,
    });

    switch (event.type) {
      case "email.delivered":
        console.log("Email delivered to:", event.data.to);
        break;
      case "email.bounced":
        console.log("Email bounced:", event.data.id);
        break;
    }

    res.status(200).send("ok");
  } catch (error) {
    console.error("Webhook error:", error);
    res.status(400).send((error as Error).message);
  }
});

app.listen(3000);
```

--------------------------------

### Initialize useSend NodeJS SDK

Source: https://docs.usesend.com/get-started/nodejs

Code examples for initializing the useSend SDK in NodeJS. Requires a useSend API key. Optionally, a custom base URL can be provided for self-hosted instances.

```javascript
import { UseSend } from "usesend-js";

const usesend = new UseSend("us_12345");
```

```javascript
const usesend = new UseSend("us_12345", "https://app.usesend.com");
```

--------------------------------

### Migrate Database

Source: https://docs.usesend.com/get-started/local

Apply database migrations to set up the necessary schema for the application. This command ensures your database is up-to-date with the required tables and fields.

```bash
pnpm db:migrate-dev
```

--------------------------------

### Clone useSend Repository

Source: https://docs.usesend.com/get-started/local

This command clones the useSend repository from GitHub to your local machine. Ensure you have forked the repository first.

```bash
git clone https://github.com/your-username/usesend.git
```

--------------------------------

### Install Dependencies for React Email with useSend

Source: https://docs.usesend.com/guides/use-with-react-email

Installs the necessary packages for using useSend with React Email. This includes the 'usesend-js' SDK and '@react-email/render' for rendering email templates.

```sh
npm install usesend-js @react-email/render
```

```sh
yarn add usesend-js @react-email/render
```

```sh
pnpm add usesend-js @react-email/render
```

```sh
bun add usesend-js @react-email/render
```

--------------------------------

### Set up Database Environment Variables

Source: https://docs.usesend.com/get-started/local

Configure your PostgreSQL and Redis database connection details by setting the DATABASE_URL and REDIS_URL environment variables. These variables are crucial for the application to connect to your database instances.

```bash
DATABASE_URL=""
REDIS_URL=""
```

--------------------------------

### Send an Email

Source: https://docs.usesend.com/get-started/python

Guide on sending a single email using the `usesend` Python SDK, including details on payload structure and optional parameters like attachments and scheduling.

```APIDOC
## Send an Email

### Description
Send a single email using the `usesend` Python SDK. The `EmailCreate` type provides editor hints, but a regular dictionary is accepted at runtime. Custom headers are forwarded to SES, with `X-Usesend-Email-ID` and `References` managed automatically.

### Method
Python

### Endpoint
`client.emails.send(payload)`

### Parameters
#### Request Body (`payload`)
- **to** (string or list[string]) - Required - Recipient email address(es).
- **from** (string) - Required - Sender email address.
- **subject** (string) - Required - Email subject.
- **html** (string) - Optional - HTML content of the email.
- **text** (string) - Optional - Plain text content of the email.
- **headers** (dict) - Optional - Custom headers to include in the email.
- **attachments** (list[dict]) - Optional - List of attachments. Each dict should have `filename` (string) and `content` (string, base64 encoded).
- **scheduledAt** (datetime) - Optional - The date and time to schedule the email for sending.

### Request Example
```python
from usesend import UseSend, types
from datetime import datetime, timedelta

client = UseSend("us_xxx")

# Example with basic fields
payload_basic: types.EmailCreate = {
    "to": "user@example.com",
    "from": "no-reply@yourdomain.com",
    "subject": "Welcome",
    "html": "<strong>Hello!</strong>",
    "headers": {"X-Campaign": "welcome"},
}
data, err = client.emails.send(payload_basic)
print(data or err)

# Example with attachments and scheduling
payload_advanced: types.EmailCreate = {
    "to": ["user1@example.com", "user2@example.com"],
    "from": "no-reply@yourdomain.com",
    "subject": "Report",
    "text": "See attached.",
    "attachments": [
        {"filename": "report.txt", "content": "SGVsbG8gd29ybGQ="},  # base64
    ],
    "scheduledAt": datetime.utcnow() + timedelta(minutes=10),
}
data, err = client.emails.create(payload_advanced)
print(data or err)
```

### Response
#### Success Response (200)
- **data** (dict) - Details of the sent email.
- **err** (None) - Indicates no error occurred.

#### Error Response
- **data** (None)
- **err** (object) - Error details.
```

--------------------------------

### Send Email with useSend NodeJS SDK

Source: https://docs.usesend.com/get-started/nodejs

Example of sending an email using the initialized useSend SDK. Supports specifying recipients, sender, subject, HTML content, plain text content, and custom headers.

```javascript
usesend.emails.send({
  to: "hello@acme.com",
  from: "hello@company.com",
  subject: "useSend email",
  html: "<p>useSend is the best open source product to send emails</p>",
  text: "useSend is the best open source product to send emails",
  headers: {
    "X-Campaign": "welcome",
  },
});
```

--------------------------------

### Create Symlink for Next.js Environment Variables

Source: https://docs.usesend.com/get-started/local

This command creates a symbolic link, allowing Next.js within the 'apps/web' directory to access the root '.env' file. This ensures environment variables are correctly loaded.

```bash
ln -s ../../.env apps/web/.env
```

--------------------------------

### Usend API Authentication Header

Source: https://docs.usesend.com/api-reference/introduction

Example of the Authorization header format required for authenticating with the Usend API. Authentication is performed using a Bearer token.

```sh
Authorization: Bearer us_12345
```

--------------------------------

### Run useSend SMTP Server with Docker Compose

Source: https://docs.usesend.com/self-hosting/overview

Command to start the useSend SMTP server in detached mode using Docker Compose. This command reads the `docker-compose.yml` file and brings up the defined services.

```bash
docker-compose up -d

```

--------------------------------

### Configure Database and Redis URLs for useSend

Source: https://docs.usesend.com/self-hosting/overview

Set the DATABASE_URL for Postgres and REDIS_URL for Redis as environment variables. These are essential for useSend's data storage and message queuing functionalities. Docker Compose simplifies this setup.

```env
DATABASE_URL="postgres://<username>:<password>@<host>:<port>/<database-name>"
REDIS_URL="redis://<username>:<password>@<host>:<port>"
```

--------------------------------

### Expose Localhost with Cloudflare Tunnel

Source: https://docs.usesend.com/get-started/local

This command uses Cloudflare Tunnel to create a secure tunnel from the internet to your local development server (http://localhost:3000). This is necessary for services that require a public callback URL, such as GitHub OAuth.

```bash
cloudflared tunnel --url http://localhost:3000
```

--------------------------------

### Verify Webhooks in Next.js App Router

Source: https://docs.usesend.com/guides/webhooks

Implement webhook signature verification within a Next.js App Router POST handler. This example uses the UseSend SDK to construct the event and handle different email event types.

```typescript
import { UseSend } from "usesend";

const usesend = new UseSend("us_your_api_key");
const webhooks = usesend.webhooks(process.env.USESEND_WEBHOOK_SECRET!);

export async function POST(request: Request) {
  try {
    const rawBody = await request.text();
    const event = webhooks.constructEvent(rawBody, {
      headers: request.headers,
    });

    switch (event.type) {
      case "email.delivered":
        console.log("Email delivered to:", event.data.to);
        break;
      case "email.bounced":
        console.log("Email bounced:", event.data.id);
        break;
      case "email.opened":
        console.log("Email opened:", event.data.id);
        break;
    }

    return new Response("ok");
  } catch (error) {
    console.error("Webhook error:", error);
    return new Response((error as Error).message, { status: 400 });
  }
}
```

--------------------------------

### Update Contact with useSend NodeJS SDK

Source: https://docs.usesend.com/get-started/nodejs

Example of updating an existing contact's information within a contact book using the useSend SDK. Requires the contact book ID, the contact's ID, and the fields to update.

```javascript
usesend.contacts.update("clzeydgeygff", contactId, {
  firstName: "Koushik",
  lastName: "KM",
});
```

--------------------------------

### Setting up Webhooks

Source: https://docs.usesend.com/guides/webhooks

Instructions on how to set up webhooks, including creating an endpoint, adding the webhook in the dashboard, and verifying signatures.

```APIDOC
## Setting up Webhooks

### Step 1: Create a webhook endpoint

Create an endpoint on your server that can receive POST requests. The endpoint must:

* Accept POST requests with JSON body
* Return a 2xx status code to acknowledge receipt
* Respond within 10 seconds

### Step 2: Add webhook in dashboard

Go to [Webhooks](https://app.usesend.com/webhooks) in your useSend dashboard and create a new webhook:

* Enter your endpoint URL
* Select which events you want to receive
* Copy the signing secret for verification

### Step 3: Verify webhook signatures

Always verify webhook signatures to ensure requests are from useSend. See the [Signature Verification](#signature-verification) section below.
```

--------------------------------

### Python SDK Initialization

Source: https://docs.usesend.com/get-started/python

How to initialize the UseSend client, with options for direct value passing or custom base URLs.

```APIDOC
## Python SDK Initialization

### Description
Initialize the UseSend client with your API key. You can pass values directly or specify a custom base URL for self-hosted instances.

### Method
Python

### Endpoint
N/A

### Parameters
- **api_key** (string) - Required - Your UseSend API key.
- **url** (string) - Optional - Custom base URL for self-hosted UseSend.

### Request Example
```python
from usesend import UseSend

# Option A: pass values directly
client = UseSend("us_xxx")

# Option B: custom base URL (self-hosted)
client = UseSend("us_xxx", url="https://your-domain.example")
```

### Response
Returns an initialized UseSend client object.
```

--------------------------------

### Initialize useSend Go Client

Source: https://docs.usesend.com/get-started/go

Initializes a new useSend client using an API key. The client can be configured with a custom base URL for self-hosted instances or a custom HTTP client.

```go
package main

import (
    "context"
    "log"

    usesend "github.com/usesend/usesend-go"
)

func main() {
    client, err := usesend.NewClient("us_12345")
    if err != nil {
        log.Fatal(err)
    }
}
```

```go
client, err := usesend.NewClient(
    "us_12345",
    usesend.WithBaseURL("https://app.usesend.com"),
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Get Contact by ID (OpenAPI)

Source: https://docs.usesend.com/api-reference/contacts/get-contact

This OpenAPI specification defines the GET endpoint for retrieving a specific contact from a contact book. It details the required path parameters (contactBookId, contactId) and the structure of the successful JSON response, including contact details and metadata.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: useSend API
servers:
  - url: https://app.usesend.com/api
security: []
paths:
  /v1/contactBooks/{contactBookId}/contacts/{contactId}:
    get:
      parameters:
        - schema:
            type: string
            example: cuiwqdj74rygf74
          required: true
          name: contactBookId
          in: path
        - schema:
            type: string
            example: cuiwqdj74rygf74
          required: true
          name: contactId
          in: path
      responses:
        '200':
          description: Retrieve the contact
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  firstName:
                    type: string
                    nullable: true
                  lastName:
                    type: string
                    nullable: true
                  email:
                    type: string
                  subscribed:
                    type: boolean
                    default: true
                  properties:
                    type: object
                    additionalProperties:
                      type: string
                  contactBookId:
                    type: string
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                required:
                  - id
                  - email
                  - properties
                  - contactBookId
                  - createdAt
                  - updatedAt

```

--------------------------------

### GET /v1/campaigns/{campaignId}

Source: https://docs.usesend.com/api-reference/campaigns/get-campaign

Retrieves the details of a specific campaign using its unique ID.

```APIDOC
## GET /v1/campaigns/{campaignId}

### Description
Retrieves the details of a specific campaign using its unique ID.

### Method
GET

### Endpoint
/v1/campaigns/{campaignId}

### Parameters
#### Path Parameters
- **campaignId** (string) - Required - The unique identifier of the campaign.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the campaign.
- **name** (string) - The name of the campaign.
- **from** (string) - The sender's email address.
- **subject** (string) - The subject line of the campaign.
- **previewText** (string) - The preview text for the email.
- **contactBookId** (string) - The ID of the contact book used for the campaign.
- **html** (string) - The HTML content of the campaign.
- **content** (string) - The plain text content of the campaign.
- **status** (string) - The current status of the campaign (e.g., 'sent', 'draft').
- **scheduledAt** (string) - The date and time the campaign is scheduled to be sent.
- **batchSize** (integer) - The number of emails to send in each batch.
- **batchWindowMinutes** (integer) - The time window in minutes for sending batches.
- **total** (integer) - The total number of emails intended for the campaign.
- **sent** (integer) - The number of emails successfully sent.
- **delivered** (integer) - The number of emails successfully delivered.
- **opened** (integer) - The number of emails opened by recipients.
- **clicked** (integer) - The number of links clicked by recipients.
- **unsubscribed** (integer) - The number of recipients who unsubscribed.
- **bounced** (integer) - The number of emails that bounced.
- **hardBounced** (integer) - The number of emails that resulted in a hard bounce.
- **complained** (integer) - The number of recipients who marked the email as spam.
- **replyTo** (array) - A list of email addresses for replies.
- **cc** (array) - A list of CC recipients.
- **bcc** (array) - A list of BCC recipients.
- **createdAt** (string) - The date and time the campaign was created.
- **updatedAt** (string) - The date and time the campaign was last updated.

#### Response Example
```json
{
  "id": "cmp_123",
  "name": "Summer Sale Campaign",
  "from": "marketing@usesend.com",
  "subject": "Don't Miss Our Summer Sale!",
  "previewText": "Get up to 50% off on all items.",
  "contactBookId": "cb_abcde",
  "html": "<html><body><h1>Summer Sale!</h1></body></html>",
  "content": "Summer Sale! Get up to 50% off.",
  "status": "sent",
  "scheduledAt": "2023-08-15T10:00:00Z",
  "batchSize": 100,
  "batchWindowMinutes": 5,
  "total": 1000,
  "sent": 1000,
  "delivered": 990,
  "opened": 300,
  "clicked": 50,
  "unsubscribed": 5,
  "bounced": 10,
  "hardBounced": 2,
  "complained": 1,
  "replyTo": [],
  "cc": [],
  "bcc": [],
  "createdAt": "2023-08-10T09:00:00Z",
  "updatedAt": "2023-08-15T11:00:00Z"
}
```
```

--------------------------------

### GET /v1/campaigns

Source: https://docs.usesend.com/api-reference/campaigns/get-campaigns

Retrieves a list of campaigns with options for pagination, status filtering, and searching.

```APIDOC
## GET /v1/campaigns

### Description
Retrieves a list of campaigns. Supports pagination, filtering by status, and searching by name or subject.

### Method
GET

### Endpoint
/v1/campaigns

### Parameters
#### Query Parameters
- **page** (string) - Optional - Page number for pagination (default: '1')
- **status** (string) - Optional - Filter campaigns by status. Allowed values: DRAFT, SCHEDULED, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED
- **search** (string) - Optional - Search campaigns by name or subject

### Response
#### Success Response (200)
- **campaigns** (array) - An array of campaign objects.
  - **id** (string) - The unique identifier for the campaign.
  - **name** (string) - The name of the campaign.
  - **from** (string) - The sender's email address.
  - **subject** (string) - The subject line of the campaign.
  - **createdAt** (string) - The date and time the campaign was created (ISO 8601 format).
  - **updatedAt** (string) - The date and time the campaign was last updated (ISO 8601 format).
  - **status** (string) - The current status of the campaign.
  - **scheduledAt** (string) - The date and time the campaign is scheduled to be sent (ISO 8601 format), can be null.
  - **total** (integer) - The total number of recipients for the campaign.
  - **sent** (integer) - The number of emails sent so far.
  - **delivered** (integer) - The number of emails successfully delivered.
  - **unsubscribed** (integer) - The number of recipients who unsubscribed.
- **totalPage** (integer) - The total number of pages available for the campaign list.

#### Response Example
```json
{
  "campaigns": [
    {
      "id": "campaign-123",
      "name": "Summer Newsletter",
      "from": "info@usesend.com",
      "subject": "Check out our latest updates!",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:30:00Z",
      "status": "COMPLETED",
      "scheduledAt": null,
      "total": 5000,
      "sent": 5000,
      "delivered": 4950,
      "unsubscribed": 50
    }
  ],
  "totalPage": 10
}
```
```

--------------------------------

### GET /v1/emails

Source: https://docs.usesend.com/api-reference/emails/list-emails

Retrieves a list of emails with optional filtering by date range, domain ID, and pagination.

```APIDOC
## GET /v1/emails

### Description
Retrieve a list of emails. Supports filtering by date range and domain ID, as well as pagination.

### Method
GET

### Endpoint
/v1/emails

### Parameters
#### Query Parameters
- **page** (string) - Optional - The page number for pagination. Defaults to '1'.
- **limit** (string) - Optional - The number of items per page. Defaults to '50'.
- **startDate** (string) - Optional - The start date for filtering emails (ISO 8601 format).
- **endDate** (string) - Optional - The end date for filtering emails (ISO 8601 format).
- **domainId** (string or array of strings) - Optional - The ID(s) of the domain(s) to filter emails by.

### Request Example
```json
{
  "example": "GET /v1/emails?page=1&limit=50&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&domainId=123"
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of email objects.
  - **id** (string) - The unique identifier for the email.
  - **to** (string or array of strings) - The recipient(s) of the email.
  - **replyTo** (string or array of strings or null) - The reply-to address(es).
  - **cc** (string or array of strings or null) - The CC recipient(s).
  - **bcc** (string or array of strings or null) - The BCC recipient(s).
  - **from** (string) - The sender's email address.
  - **subject** (string) - The subject of the email.
  - **html** (string or null) - The HTML content of the email.
  - **text** (string or null) - The plain text content of the email.
  - **createdAt** (string) - The timestamp when the email was created.
  - **updatedAt** (string) - The timestamp when the email was last updated.
  - **latestStatus** (string or null) - The latest status of the email (e.g., SENT, BOUNCED, DELIVERED).
  - **scheduledAt** (string or null) - The timestamp when the email is scheduled to be sent.
  - **domainId** (number or null) - The ID of the domain associated with the email.
- **count** (number) - The total number of emails returned.

#### Response Example
```json
{
  "example": {
    "data": [
      {
        "id": "email_abc123",
        "to": "recipient@example.com",
        "replyTo": null,
        "cc": null,
        "bcc": null,
        "from": "sender@usesend.com",
        "subject": "Test Email",
        "html": "<p>This is a test email.</p>",
        "text": "This is a test email.",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:05:00Z",
        "latestStatus": "SENT",
        "scheduledAt": null,
        "domainId": 123
      }
    ],
    "count": 1
  }
}
```
```

--------------------------------

### Initialize UseSend Python Client

Source: https://docs.usesend.com/get-started/python

Initializes the UseSend Python client. You can pass the API key directly or specify a custom base URL for self-hosted instances.

```python
from usesend import UseSend, types


# Option A: pass values directly (helpful in scripts/tests)
client = UseSend("us_xxx")

# Option B: custom base URL (self-hosted)
client = UseSend("us_xxx", url="https://your-domain.example")
```

--------------------------------

### GET /v1/domains/{id}

Source: https://docs.usesend.com/api-reference/domains/get-domain

Retrieves the details of a specific domain by its ID. This endpoint allows you to fetch comprehensive information about a domain, including its configuration, status, and DNS records.

```APIDOC
## GET /v1/domains/{id}

### Description
Retrieve the domain details by its ID.

### Method
GET

### Endpoint
/v1/domains/{id}

### Parameters
#### Path Parameters
- **id** (number) - Optional - The ID of the domain

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **id** (number) - The ID of the domain
- **name** (string) - The name of the domain
- **teamId** (number) - The ID of the team
- **status** (string) - The status of the domain (enum: NOT_STARTED, PENDING, SUCCESS, FAILED, TEMPORARY_FAILURE)
- **region** (string) - The region of the domain (default: us-east-1)
- **clickTracking** (boolean) - Whether click tracking is enabled (default: false)
- **openTracking** (boolean) - Whether open tracking is enabled (default: false)
- **publicKey** (string) - The public key for the domain
- **dkimStatus** (string) - The DKIM status (nullable)
- **spfDetails** (string) - SPF details (nullable)
- **createdAt** (string) - The creation timestamp
- **updatedAt** (string) - The last update timestamp
- **dmarcAdded** (boolean) - Whether DMARC has been added (default: false)
- **isVerifying** (boolean) - Whether the domain is currently verifying (default: false)
- **errorMessage** (string) - Any error message associated with the domain (nullable)
- **subdomain** (string) - The subdomain associated with the domain (nullable)
- **verificationError** (string) - Any verification error (nullable)
- **lastCheckedTime** (string) - The timestamp of the last check (nullable)
- **dnsRecords** (array) - An array of DNS records
  - **type** (string) - DNS record type (enum: MX, TXT)
  - **name** (string) - DNS record name
  - **value** (string) - DNS record value
  - **ttl** (string) - DNS record TTL
  - **priority** (string) - DNS record priority (nullable)
  - **status** (string) - The status of the DNS record (enum: NOT_STARTED, PENDING, SUCCESS, FAILED, TEMPORARY_FAILURE)
  - **recommended** (boolean) - Whether the record is recommended

#### Response Example
```json
{
  "id": 1,
  "name": "example.com",
  "teamId": 1,
  "status": "SUCCESS",
  "region": "us-east-1",
  "clickTracking": false,
  "openTracking": false,
  "publicKey": "pk_test_...",
  "dkimStatus": null,
  "spfDetails": null,
  "createdAt": "2023-01-01T12:00:00Z",
  "updatedAt": "2023-01-01T12:00:00Z",
  "dmarcAdded": false,
  "isVerifying": false,
  "errorMessage": null,
  "subdomain": null,
  "verificationError": null,
  "lastCheckedTime": null,
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:amazonses.com ~all",
      "ttl": "Auto",
      "priority": null,
      "status": "SUCCESS",
      "recommended": true
    }
  ]
}
```
```

--------------------------------

### Send Email using useSend SDK

Source: https://docs.usesend.com/guides/use-with-react-email

Demonstrates how to send an email using the useSend SDK. It initializes the SDK with an API key, renders a React Email template to HTML, and then sends the email with specified recipients, subject, and content.

```ts
import { UseSend } from "usesend-js";
import { render } from "@react-email/render";
import { Email } from "./email";

const usesend = new UseSend("us_your_usesend_api_key");

  const html = await render(<Email url="https://usesend.com" />);

const response = await usesend.emails.send({
  to: "hello@usesend.com",
  from: "hello@usesend.com",
  subject: "useSend email",
  html,
});
```

--------------------------------

### Generate NextAuth Secret

Source: https://docs.usesend.com/get-started/local

This command generates a secure random base64 string to be used as the NEXTAUTH_SECRET environment variable. This is essential for NextAuth.js security.

```bash
openssl rand -base64 32
```

--------------------------------

### GET /v1/contactBooks/{contactBookId}/contacts

Source: https://docs.usesend.com/api-reference/contacts/get-contacts

Retrieves a list of contacts from a specified contact book. Supports filtering by email, pagination, and specific contact IDs.

```APIDOC
## GET /v1/contactBooks/{contactBookId}/contacts

### Description
Retrieves multiple contacts from a specific contact book. You can filter contacts by email addresses, paginate the results, and specify which contact IDs to retrieve.

### Method
GET

### Endpoint
/v1/contactBooks/{contactBookId}/contacts

### Parameters
#### Path Parameters
- **contactBookId** (string) - Required - The ID of the contact book to retrieve contacts from.

#### Query Parameters
- **emails** (string) - Optional - A comma-separated list of email addresses to filter contacts by.
- **page** (number) - Optional - The page number for pagination.
- **limit** (number) - Optional - The number of contacts to return per page.
- **ids** (string) - Optional - A comma-separated list of contact IDs to retrieve.

### Request Example
```json
{
  "example": "GET /v1/contactBooks/cuiwqdj74rygf74/contacts?emails=test@example.com,another@example.com&page=1&limit=20&ids=123,456"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the contact.
- **firstName** (string, nullable) - The first name of the contact.
- **lastName** (string, nullable) - The last name of the contact.
- **email** (string) - The email address of the contact.
- **subscribed** (boolean) - Indicates if the contact is subscribed (defaults to true).
- **properties** (object) - Additional properties associated with the contact. Additional properties are strings.
- **contactBookId** (string) - The ID of the contact book this contact belongs to.
- **createdAt** (string) - The timestamp when the contact was created.
- **updatedAt** (string) - The timestamp when the contact was last updated.

#### Response Example
```json
{
  "example": [
    {
      "id": "contact123",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "subscribed": true,
      "properties": {
        "customField1": "value1",
        "customField2": "value2"
      },
      "contactBookId": "cuiwqdj74rygf74",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Get a Contact by ID in Python

Source: https://docs.usesend.com/get-started/python

Retrieves a specific contact from a contact book using its ID with the UseSend Python SDK. Requires both the `book_id` and `contact_id`.

```python
from usesend import UseSend

contact, err = client.contacts.get("book_123", "contact_456")
```

--------------------------------

### GET /v1/domains

Source: https://docs.usesend.com/api-reference/domains/list-domains

Retrieves a list of domains accessible by the API key. This endpoint provides detailed information about each domain, including its ID, name, status, DNS records, and tracking configurations.

```APIDOC
## GET /v1/domains

### Description
Retrieves a list of domains accessible by the API key. This endpoint provides detailed information about each domain, including its ID, name, status, DNS records, and tracking configurations.

### Method
GET

### Endpoint
/v1/domains

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **id** (number) - The ID of the domain
- **name** (string) - The name of the domain
- **teamId** (number) - The ID of the team
- **status** (string) - The current status of the domain (e.g., NOT_STARTED, PENDING, SUCCESS, FAILED)
- **region** (string) - The region the domain is associated with
- **clickTracking** (boolean) - Whether click tracking is enabled
- **openTracking** (boolean) - Whether open tracking is enabled
- **publicKey** (string) - The public key for the domain
- **dkimStatus** (string, nullable) - The DKIM status
- **spfDetails** (string, nullable) - SPF record details
- **createdAt** (string) - Timestamp of when the domain was created
- **updatedAt** (string) - Timestamp of when the domain was last updated
- **dmarcAdded** (boolean) - Whether DMARC record has been added
- **isVerifying** (boolean) - Whether the domain is currently being verified
- **errorMessage** (string, nullable) - Any error message associated with the domain
- **subdomain** (string, nullable) - The subdomain associated with the domain
- **verificationError** (string, nullable) - Any verification error
- **lastCheckedTime** (string, nullable) - Timestamp of the last DNS check
- **dnsRecords** (array) - An array of DNS records associated with the domain
  - **type** (string) - DNS record type (e.g., MX, TXT)
  - **name** (string) - DNS record name
  - **value** (string) - DNS record value
  - **ttl** (string) - DNS record TTL
  - **priority** (string, nullable) - DNS record priority
  - **status** (string) - Status of the DNS record
  - **recommended** (boolean) - Whether the record is recommended

#### Response Example
```json
[
  {
    "id": 1,
    "name": "example.com",
    "teamId": 1,
    "status": "SUCCESS",
    "region": "us-east-1",
    "clickTracking": false,
    "openTracking": false,
    "publicKey": "pk_example",
    "dkimStatus": null,
    "spfDetails": null,
    "createdAt": "2023-01-01T12:00:00Z",
    "updatedAt": "2023-01-01T12:00:00Z",
    "dmarcAdded": false,
    "isVerifying": false,
    "errorMessage": null,
    "subdomain": null,
    "verificationError": null,
    "lastCheckedTime": null,
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "mail",
        "value": "v=spf1 include:amazonses.com ~all",
        "ttl": "Auto",
        "priority": "10",
        "status": "SUCCESS",
        "recommended": true
      }
    ]
  }
]
```
```

--------------------------------

### Send a Single Email with UseSend Python SDK

Source: https://docs.usesend.com/get-started/python

Demonstrates how to send a single email using the UseSend Python SDK. It includes setting recipient, sender, subject, HTML content, and custom headers. The `EmailCreate` type provides editor hints.

```python
from usesend import UseSend, types

client = UseSend("us_xxx")

payload: types.EmailCreate = {
    "to": "user@example.com",
    "from": "no-reply@yourdomain.com",
    "subject": "Welcome",
    "html": "<strong>Hello!</strong>",
    "headers": {"X-Campaign": "welcome"},
}

data, err = client.emails.send(payload)
print(data or err)
```

--------------------------------

### GET /v1/contactBooks/{contactBookId}

Source: https://docs.usesend.com/api-reference/contacts/get-contact-book

Retrieves a specific contact book by its ID. This endpoint allows you to fetch details about a contact book, including its name, associated team, properties, emoji, and creation/update timestamps.

```APIDOC
## GET /v1/contactBooks/{contactBookId}

### Description
Retrieves a specific contact book by its ID. This endpoint allows you to fetch details about a contact book, including its name, associated team, properties, emoji, and creation/update timestamps.

### Method
GET

### Endpoint
/v1/contactBooks/{contactBookId}

### Parameters
#### Path Parameters
- **contactBookId** (string) - Required - The unique identifier of the contact book to retrieve.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the contact book.
- **name** (string) - The name of the contact book.
- **teamId** (number) - The ID of the team associated with the contact book.
- **properties** (object) - Additional properties for the contact book. Additional properties are strings.
- **emoji** (string) - An emoji representing the contact book.
- **createdAt** (string) - The timestamp when the contact book was created.
- **updatedAt** (string) - The timestamp when the contact book was last updated.
- **_count** (object) - An object containing counts related to the contact book.
  - **contacts** (number) - The number of contacts within the contact book.

#### Response Example
```json
{
  "id": "clx1234567890",
  "name": "My Contacts",
  "teamId": 123,
  "properties": {
    "customField1": "value1",
    "customField2": "value2"
  },
  "emoji": "😊",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:30:00Z",
  "_count": {
    "contacts": 50
  }
}
```

#### Error Response (403)
- **error** (string) - Description of the error, e.g., "Forbidden - API key doesn't have access".

#### Error Response (404)
- **error** (string) - Description of the error, e.g., "Contact book not found".

```