Send Campaign

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
  }'

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"
  }'

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`)

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',
})

{
  "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"
}

{
  "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"
}

{
  "error": "Missing required fields or recipients"
}

POST

api

campaigns

send

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
  }'

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"
  }'

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`)

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',
})

{
  "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"
}

{
  "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"
}

{
  "error": "Missing required fields or recipients"
}

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.

Sender identity is controlled by your project’s email settings. Set sender_name and sender_email in Email Sender Settings to replace the default Gately <hello@usegately.com> From address.

Headers

string

required

Bearer YOUR_API_KEY

string

Your project UUID. Not required if the API key already encodes the project.

Request Body

string

required

Display name stored in the dashboard (e.g. "June Newsletter")

string

required

Email subject line shown to recipients

string

required

HTML body of the email. YouTube <iframe> embeds are automatically converted to linked thumbnail images.

string[]

Explicit list of email addresses to send to

string[]

IDs of contact lists — all members of each list receive the email

string[]

IDs of contact segments — filtered contacts receive the email

boolean

Set true to send to every contact in the project

string

ISO 8601 datetime to schedule delivery (e.g. "2025-07-01T09:00:00Z"). Omit to send immediately.

object[]

Optional file attachments. Each object must have content (base64), filename, and type (MIME). Max 10 MB per file.

Show Attachment fields

string

required

Base64-encoded file content

string

required

File name including extension (e.g. "report.pdf")

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

string

default:"attachment"

"attachment" or "inline"

Response

boolean

true when the campaign was created and sending initiated

object

The created campaign record

number

Total unique addresses targeted

number

Emails accepted by the mail service

number

Emails that failed to send

string

Human-readable summary (e.g. "Email campaign sent to 835 of 842 recipients")

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
  }'

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"
  }'

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`)

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',
})

{
  "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"
}

{
  "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"
}

{
  "error": "Missing required fields or recipients"
}

Overview

Authentication

Members

Project Settings

Email Campaigns

Plans

Contacts

Discussions

Transactional Email

Webhooks

Headers

Request Body

Response

​Headers

​Request Body

​Response

Headers

Request Body

Response