Create, create-or-update, get, update, delete, and batch-update contacts within a list, including their field values and tag assignments.
openapi: 3.0.1
info:
title: EmailOctopus v2 API
description: >-
The EmailOctopus v2 REST API lets developers manage subscriber lists,
contacts, custom fields, tags, campaigns, automations, and campaign
reports. All requests are made over HTTPS to https://api.emailoctopus.com
and authenticated with a Bearer API key in the Authorization header.
termsOfService: https://emailoctopus.com/terms
contact:
name: EmailOctopus Support
url: https://help.emailoctopus.com
version: '2.0'
servers:
- url: https://api.emailoctopus.com
security:
- api_key: []
tags:
- name: List
- name: Contact
- name: Field
- name: Tag
- name: Campaign
- name: Automation
paths:
/lists:
get:
operationId: getAllLists
tags:
- List
summary: Get all lists
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
responses:
'200':
description: A paged collection of lists.
content:
application/json:
schema:
$ref: '#/components/schemas/ListCollection'
post:
operationId: createList
tags:
- List
summary: Create list
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
maxLength: 255
description: The name of the list.
example: New clients list
responses:
'200':
description: The created list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
/lists/{list_id}:
parameters:
- $ref: '#/components/parameters/ListId'
get:
operationId: getList
tags:
- List
summary: Get list
responses:
'200':
description: The requested list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
put:
operationId: updateList
tags:
- List
summary: Update list
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 255
description: The name of the list.
example: New clients list
responses:
'200':
description: The updated list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
delete:
operationId: deleteList
tags:
- List
summary: Delete a list
responses:
'204':
description: The list was deleted.
/lists/{list_id}/contacts:
parameters:
- $ref: '#/components/parameters/ListId'
get:
operationId: getContacts
tags:
- Contact
summary: Get contacts
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
responses:
'200':
description: A paged collection of contacts.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCollection'
post:
operationId: createContact
tags:
- Contact
summary: Create contact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactWrite'
responses:
'200':
description: The created contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
put:
operationId: createOrUpdateContact
tags:
- Contact
summary: Create or update contact
description: >-
Creates a contact, or updates it if a contact with the supplied email
address already exists on the list.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactWrite'
responses:
'200':
description: The created or updated contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
/lists/{list_id}/contacts/batch:
parameters:
- $ref: '#/components/parameters/ListId'
put:
operationId: updateMultipleContacts
tags:
- Contact
summary: Update multiple list contacts
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- contacts
properties:
contacts:
type: array
description: The contacts to create or update.
items:
$ref: '#/components/schemas/ContactWrite'
responses:
'200':
description: The result of each contact operation in the batch.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
email_address:
type: string
example: otto@example.com
status:
type: string
example: success
/lists/{list_id}/contacts/{contact_id}:
parameters:
- $ref: '#/components/parameters/ListId'
- $ref: '#/components/parameters/ContactId'
get:
operationId: getContact
tags:
- Contact
summary: Get contact
responses:
'200':
description: The requested contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
put:
operationId: updateContact
tags:
- Contact
summary: Update contact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactWrite'
responses:
'200':
description: The updated contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
delete:
operationId: deleteContact
tags:
- Contact
summary: Delete contact
responses:
'204':
description: The contact was deleted.
/lists/{list_id}/fields:
parameters:
- $ref: '#/components/parameters/ListId'
post:
operationId: createField
tags:
- Field
summary: Create field
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Field'
responses:
'200':
description: The created field.
content:
application/json:
schema:
$ref: '#/components/schemas/Field'
/lists/{list_id}/fields/{tag}:
parameters:
- $ref: '#/components/parameters/ListId'
- $ref: '#/components/parameters/Tag'
put:
operationId: updateField
tags:
- Field
summary: Update field
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Field'
responses:
'200':
description: The updated field.
content:
application/json:
schema:
$ref: '#/components/schemas/Field'
delete:
operationId: deleteField
tags:
- Field
summary: Delete field
responses:
'204':
description: The field was deleted.
/lists/{list_id}/tags:
parameters:
- $ref: '#/components/parameters/ListId'
get:
operationId: getAllTags
tags:
- Tag
summary: Get all tags
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
responses:
'200':
description: A paged collection of tags.
content:
application/json:
schema:
$ref: '#/components/schemas/TagCollection'
post:
operationId: createTag
tags:
- Tag
summary: Create tag
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
responses:
'200':
description: The created tag.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
/lists/{list_id}/tags/{tag}:
parameters:
- $ref: '#/components/parameters/ListId'
- $ref: '#/components/parameters/Tag'
put:
operationId: updateTag
tags:
- Tag
summary: Update tag
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
responses:
'200':
description: The updated tag.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
delete:
operationId: deleteTag
tags:
- Tag
summary: Delete tag
responses:
'204':
description: The tag was deleted.
/campaigns:
get:
operationId: getAllCampaigns
tags:
- Campaign
summary: Get all campaigns
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
responses:
'200':
description: A paged collection of campaigns.
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCollection'
/campaigns/{campaign_id}:
parameters:
- $ref: '#/components/parameters/CampaignId'
get:
operationId: getCampaign
tags:
- Campaign
summary: Get campaign
responses:
'200':
description: The requested campaign.
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
/campaigns/{campaign_id}/reports/summary:
parameters:
- $ref: '#/components/parameters/CampaignId'
get:
operationId: getCampaignSummaryReport
tags:
- Campaign
summary: Campaign summary report
responses:
'200':
description: A summary report of the campaign's performance.
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignSummaryReport'
/campaigns/{campaign_id}/reports/links:
parameters:
- $ref: '#/components/parameters/CampaignId'
get:
operationId: getCampaignLinksReport
tags:
- Campaign
summary: Campaign links report
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
responses:
'200':
description: A report of click activity per link in the campaign.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
url:
type: string
example: https://emailoctopus.com
clicked:
type: object
properties:
total:
type: integer
example: 110
unique:
type: integer
example: 85
/campaigns/{campaign_id}/reports:
parameters:
- $ref: '#/components/parameters/CampaignId'
get:
operationId: getCampaignContactReports
tags:
- Campaign
summary: Campaign contact reports
description: >-
Per-contact activity for a campaign. The report type (sent, opened,
clicked, bounced, complained, unsubscribed, etc.) is selected via the
type query parameter.
parameters:
- name: type
in: query
required: true
description: The type of contact report to return.
schema:
type: string
enum:
- sent
- opened
- clicked
- bounced
- complained
- unsubscribed
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
responses:
'200':
description: A paged collection of contacts for the requested report type.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
paging:
$ref: '#/components/schemas/Paging'
/automations/{automation_id}/queue:
parameters:
- name: automation_id
in: path
required: true
description: The ID of the automation.
schema:
type: string
example: 00000000-0000-0000-0000-000000000000
post:
operationId: startAutomation
tags:
- Automation
summary: Start an automation for a contact
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- list_id
- contact_id
properties:
list_id:
type: string
description: The ID of the list the contact belongs to.
example: 00000000-0000-0000-0000-000000000000
contact_id:
type: string
description: The ID of the contact to enter into the automation.
example: 00000000-0000-0000-0000-000000000000
responses:
'202':
description: The contact was queued into the automation.
components:
securitySchemes:
api_key:
type: http
scheme: bearer
description: >-
Bearer API key in the Authorization header. Create a key at
https://api.emailoctopus.com/developer/api-keys/create
parameters:
ListId:
name: list_id
in: path
required: true
description: The ID of the list.
schema:
type: string
example: 00000000-0000-0000-0000-000000000000
ContactId:
name: contact_id
in: path
required: true
description: The ID of the contact (a UUID or the MD5 hash of the lowercased email).
schema:
type: string
example: 00000000-0000-0000-0000-000000000000
CampaignId:
name: campaign_id
in: path
required: true
description: The ID of the campaign.
schema:
type: string
example: 00000000-0000-0000-0000-000000000000
Tag:
name: tag
in: path
required: true
description: The tag identifier.
schema:
type: string
example: my tag
Limit:
name: limit
in: query
required: false
description: The maximum number of records to return per page.
schema:
type: integer
default: 100
maximum: 1000
StartingAfter:
name: starting_after
in: query
required: false
description: A cursor for pagination; the ID of the last record on the previous page.
schema:
type: string
schemas:
List:
type: object
properties:
id:
type: string
description: The ID of the list.
example: 00000000-0000-0000-0000-000000000000
name:
type: string
maxLength: 255
description: The name of the list.
example: New clients list
double_opt_in:
type: boolean
description: If double opt-in has been enabled on the list.
example: false
fields:
type: array
description: The custom fields available on the list.
items:
$ref: '#/components/schemas/Field'
counts:
type: object
description: Contact counts by status.
properties:
pending:
type: integer
example: 1
subscribed:
type: integer
example: 10
unsubscribed:
type: integer
example: 2
created_at:
type: string
format: date-time
description: When the list was created, in ISO 8601 format.
example: '2024-10-07T12:00:00+00:00'
ListCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/List'
paging:
$ref: '#/components/schemas/Paging'
Field:
type: object
properties:
label:
type: string
description: A human readable label for the field.
example: What is your hometown?
tag:
type: string
description: The ID used to reference the field in your emails.
example: Hometown
type:
type: string
description: The type of the field.
example: text
enum:
- text
- number
- date
- choice_single
- choice_multiple
choices:
type: array
description: An array of choices for choice fields.
items:
type: string
example:
- One
- Two
fallback:
type: string
nullable: true
description: A default value used in campaigns when no other value is available.
example: Unknown
Tag:
type: object
properties:
tag:
type: string
description: The name of the tag.
example: my tag
TagCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tag'
paging:
$ref: '#/components/schemas/Paging'
Contact:
type: object
description: Details of a contact of a list.
properties:
id:
type: string
description: The ID of the contact.
example: 00000000-0000-0000-0000-000000000000
email_address:
type: string
description: The email address of the contact.
example: otto@example.com
fields:
type: object
description: Key/value pairs of field values, keyed by field tag.
additionalProperties: true
example:
referral: Otto
birthday: '2015-12-01'
status:
type: string
description: The subscription status of the contact.
example: subscribed
enum:
- subscribed
- unsubscribed
- pending
tags:
type: array
description: Tags associated with the contact.
items:
type: string
example:
- vip
created_at:
type: string
format: date-time
example: '2024-10-07T12:00:00+00:00'
last_updated_at:
type: string
format: date-time
example: '2024-10-07T12:00:00+00:00'
ContactWrite:
type: object
required:
- email_address
properties:
email_address:
type: string
description: The email address of the contact.
example: otto@example.com
fields:
type: object
description: >-
Key/value pairs of field values, keyed by field tag. Pass null to
remove a field from the contact.
additionalProperties: true
example:
referral: Otto
birthday: '2015-12-01'
tags:
type: object
description: >-
Tags to add or remove, keyed by tag name with a boolean value
(true to add, false to remove).
additionalProperties:
type: boolean
example:
vip: true
status:
type: string
description: The subscription status to set for the contact.
example: subscribed
enum:
- subscribed
- unsubscribed
- pending
ContactCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
paging:
$ref: '#/components/schemas/Paging'
Campaign:
type: object
description: Details of a campaign.
properties:
id:
type: string
description: The ID of the campaign.
example: 00000000-0000-0000-0000-000000000000
status:
type: string
description: The status of the campaign.
example: draft
enum:
- draft
- sending
- sent
- error
name:
type: string
maxLength: 255
description: The name of the campaign.
example: New clients campaign
subject:
type: string
maxLength: 255
description: The subject of the campaign.
example: Hello
to:
type: array
description: The IDs of the lists the campaign was sent to.
items:
type: string
example:
- 00000000-0000-0000-0000-000000000000
from:
type: object
description: The sender of the campaign.
properties:
name:
type: string
example: Otto Octopus
email_address:
type: string
example: otto@example.com
content:
type: object
description: The content of the campaign.
properties:
html:
type: string
example: <p>Hello</p>
plain_text:
type: string
example: Hello
created_at:
type: string
format: date-time
example: '2024-10-07T12:00:00+00:00'
sent_at:
type: string
format: date-time
nullable: true
example: '2024-10-08T12:00:00+00:00'
CampaignCollection:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Campaign'
paging:
$ref: '#/components/schemas/Paging'
CampaignSummaryReport:
type: object
description: A summary of a campaign's performance.
properties:
id:
type: string
example: 00000000-0000-0000-0000-000000000000
sent:
type: integer
description: The number of contacts that were sent to.
example: 200
bounced:
type: object
properties:
hard:
type: integer
example: 10
soft:
type: integer
example: 5
opened:
type: object
properties:
total:
type: integer
example: 110
unique:
type: integer
example: 85
clicked:
type: object
properties:
total:
type: integer
example: 110
unique:
type: integer
example: 85
complained:
type: integer
example: 50
unsubscribed:
type: integer
example: 20
Paging:
type: object
description: Cursor pagination metadata.
properties:
next:
type: string
nullable: true
description: The path to the next page of results, or null if none.
example: /lists?limit=100&starting_after=00000000-0000-0000-0000-000000000000
previous:
type: string
nullable: true
description: The path to the previous page of results, or null if none.
example: null