> ## Documentation Index
> Fetch the complete documentation index at: https://usegately.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Campaign

> Create and send (or schedule) an email campaign in one request

Creates a campaign record and immediately sends it to all resolved recipients. Pass `scheduled_at` to queue it for later instead.

At least one recipient source is required — you can combine multiple.

<Info>
  **Sender identity** is controlled by your project's email settings. Set `sender_name` and `sender_email` in [Email Sender Settings](/docs/api-reference/settings/email) to replace the default `Gately <hello@usegately.com>` From address.
</Info>

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="X-Project-ID" type="string">
  Your project UUID. Not required if the API key already encodes the project.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  Display name stored in the dashboard (e.g. `"June Newsletter"`)
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line shown to recipients
</ParamField>

<ParamField body="content" type="string" required>
  HTML body of the email. YouTube `<iframe>` embeds are automatically converted to linked thumbnail images.
</ParamField>

<ParamField body="recipient_emails" type="string[]">
  Explicit list of email addresses to send to
</ParamField>

<ParamField body="recipient_list_ids" type="string[]">
  IDs of contact lists — all members of each list receive the email
</ParamField>

<ParamField body="recipient_segment_ids" type="string[]">
  IDs of contact segments — filtered contacts receive the email
</ParamField>

<ParamField body="recipient_all_contacts" type="boolean">
  Set `true` to send to every contact in the project
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 datetime to schedule delivery (e.g. `"2025-07-01T09:00:00Z"`). Omit to send immediately.
</ParamField>

<ParamField body="attachments" type="object[]">
  Optional file attachments. Each object must have `content` (base64), `filename`, and `type` (MIME). Max 10 MB per file.

  <Expandable title="Attachment fields">
    <ParamField body="content" type="string" required>
      Base64-encoded file content
    </ParamField>

    <ParamField body="filename" type="string" required>
      File name including extension (e.g. `"report.pdf"`)
    </ParamField>

    <ParamField body="type" type="string" required>
      MIME type. Allowed: `application/pdf`, `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `text/plain`, `text/csv`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
    </ParamField>

    <ParamField body="disposition" type="string" default="attachment">
      `"attachment"` or `"inline"`
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the campaign was created and sending initiated
</ResponseField>

<ResponseField name="campaign" type="object">
  The created campaign record
</ResponseField>

<ResponseField name="total_recipients" type="number">
  Total unique addresses targeted
</ResponseField>

<ResponseField name="successful_sends" type="number">
  Emails accepted by the mail service
</ResponseField>

<ResponseField name="failed_sends" type="number">
  Emails that failed to send
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable summary (e.g. `"Email campaign sent to 835 of 842 recipients"`)
</ResponseField>

<RequestExample>
  ```bash Send immediately theme={null}
  curl -X POST "https://api.usegately.com/api/v1/campaigns/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Project-ID: YOUR_PROJECT_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "June Newsletter",
      "subject": "What we shipped this month",
      "content": "<h1>June Update</h1><p>Here is what we built...</p>",
      "recipient_all_contacts": true
    }'
  ```

  ```bash Schedule for later theme={null}
  curl -X POST "https://api.usegately.com/api/v1/campaigns/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Project-ID: YOUR_PROJECT_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Product Launch",
      "subject": "Introducing our new feature!",
      "content": "<h1>Hello!</h1><p>Check out what we built.</p>",
      "recipient_list_ids": ["list-uuid-here"],
      "scheduled_at": "2025-07-01T09:00:00Z"
    }'
  ```

  ```typescript SDK — send now theme={null}
  import { GatelyCampaigns } from '@gately/sdk'

  const campaigns = new GatelyCampaigns({ projectId: 'YOUR_PROJECT_ID' })

  const result = await campaigns.send({
    name: 'June Newsletter',
    subject: 'What we shipped this month',
    content: '<h1>June Update</h1><p>Here is what we built...</p>',
    recipient_all_contacts: true,
  })

  console.log(`Sent to ${result.successful_sends} recipients`)
  ```

  ```typescript SDK — schedule theme={null}
  import { GatelyCampaigns } from '@gately/sdk'

  const campaigns = new GatelyCampaigns({ projectId: 'YOUR_PROJECT_ID' })

  await campaigns.send({
    name: 'Product Launch',
    subject: 'Introducing our new feature!',
    content: '<h1>Hello!</h1><p>Check out what we built.</p>',
    recipient_list_ids: ['list-uuid-here'],
    scheduled_at: '2025-07-01T09:00:00Z',
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Sent immediately theme={null}
  {
    "success": true,
    "campaign": {
      "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
      "name": "June Newsletter",
      "subject": "What we shipped this month",
      "status": "sent",
      "total_recipients": 842,
      "delivered_count": 835,
      "sent_at": "2025-06-15T10:00:00.000Z"
    },
    "total_recipients": 842,
    "successful_sends": 835,
    "failed_sends": 7,
    "message": "Email campaign sent to 835 of 842 recipients"
  }
  ```

  ```json Scheduled theme={null}
  {
    "success": true,
    "campaign": {
      "id": "b2c3d4e5-f6a7-4890-bcde-f12345678901",
      "name": "Product Launch",
      "status": "scheduled",
      "scheduled_at": "2025-07-01T09:00:00.000Z",
      "total_recipients": 500
    },
    "total_recipients": 500,
    "successful_sends": 0,
    "failed_sends": 0,
    "message": "Campaign scheduled for 2025-07-01T09:00:00Z"
  }
  ```

  ```json Validation error theme={null}
  {
    "error": "Missing required fields or recipients"
  }
  ```
</ResponseExample>