openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Marketing Campaigns Contacts API
summary: The Twilio SendGrid Marketing Campaigns Contacts API allows you to manage
all of your marketing contacts programmatically.
description: 'The Twilio SendGrid Marketing Campaigns Contacts API allows you to
manage all of your marketing contacts programmatically. You can also import and
export contacts using this API. The Contacts API allows you to associate contacts
with lists and segments; however, to manage the lists and segments themselves,
see the [Lists API](https://docs.sendgrid.com/api-reference/lists/) and [Segments
API](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2/).
You can also manage your marketing contacts with the [Marketing Campaigns application
user interface](https://mc.sendgrid.com/contacts). See [**How to Send Email with
New Marketing Campaigns**](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns)
for more information.'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: mc_contacts
servers:
- url: https://api.sendgrid.com
description: The Twilio SendGrid v3 API
paths:
/v3/marketing/contacts:
put:
operationId: UpdateContact
summary: Add or Update a Contact
tags:
- Contacts
description: '**This endpoint allows the [upsert](https://en.wiktionary.org/wiki/upsert)
(insert or update) of up to 30,000 contacts, or 6MB of data, whichever is
lower**.
Because the creation and update of contacts is an asynchronous process, the
response will not contain immediate feedback on the processing of your upserted
contacts. Rather, it will contain an HTTP 202 response indicating the contacts
are queued for processing or an HTTP 4XX error containing validation errors.
Should you wish to get the resulting contact''s ID or confirm that your contacts
have been updated or added, you can use the [Get Contacts by Identifiers operation](https://www.twilio.com/docs/sendgrid/api-reference/contacts/get-contacts-by-identifiers).
Please note that custom fields need to have been already created if you wish
to set their values for the contacts being upserted. To do this, please use
the [Create Custom Field Definition endpoint](https://www.twilio.com/docs/sendgrid/api-reference/custom-fields/create-custom-field-definition).
You will see a `job_id` in the response to your request. This can be used
to check the status of your upsert job. To do so, please use the [Import Contacts
Status endpoint](https://www.twilio.com/docs/sendgrid/api-reference/contacts/import-contacts-status).
If the contact already exists in the system, any entries submitted via this
endpoint will update the existing contact. In order to update a contact, all
of its existing identifiers must be present. Any fields omitted from the request
will remain as they were. A contact''s ID cannot be used to update the contact.
The email field will be changed to all lower-case. If a contact is added with
an email that exists but contains capital letters, the existing contact with
the all lower-case email will be updated.'
requestBody:
content:
application/json:
schema:
type: object
properties:
list_ids:
type: array
description: An array of List ID strings that this contact will
be added to.
items:
type: string
format: uuid
contacts:
type: array
description: One or more contacts objects that you intend to upsert.
Each contact needs to include at least one of `email`, `phone_number_id`,
`external_id`, or `anonymous_id` as an identifier.
minItems: 1
maxItems: 30000
items:
$ref: '#/components/schemas/ContactRequest'
required:
- contacts
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
description: Indicates that the contacts are queued for processing.
Check the job status with the "Import Contacts Status" endpoint.
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
delete:
operationId: DeleteContact
summary: Delete Contacts
tags:
- Contacts
description: "**This endpoint can be used to delete one or more contacts**.\n\
\nThe query parameter `ids` must set to a comma-separated list of contact\
\ IDs for bulk contact deletion.\n\nThe query parameter `delete_all_contacts`\
\ must be set to `\"true\"` to delete **all** contacts. \n\nYou must set either\
\ `ids` or `delete_all_contacts`.\n\nDeletion jobs are processed asynchronously.\n\
\nTwilio SendGrid recommends exporting your contacts regularly as a backup\
\ to avoid issues or lost data."
parameters:
- name: delete_all_contacts
in: query
description: Must be set to `"true"` to delete all contacts.
required: false
schema:
type: string
- name: ids
in: query
description: A comma-separated list of contact IDs.
required: false
schema:
type: string
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
description: The deletion job has been accepted and is being processed.
properties:
job_id:
type: object
description: The deletion job ID.
required:
- job_id
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
required:
- errors
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
get:
operationId: ListContact
summary: Get Sample Contacts
tags:
- Contacts
description: "**This endpoint will return up to 50 of the most recent contacts\
\ uploaded or attached to a list**. \n\nThis list will then be sorted by email\
\ address.\n\nThe full contact count is also returned.\n\nPlease note that\
\ pagination of the contacts has been deprecated.\n\nTwilio SendGrid recommends\
\ exporting your contacts regularly as a backup to avoid issues or lost data."
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ContactDetails3'
_metadata:
$ref: '#/components/schemas/SelfMetadata'
contact_count:
type: integer
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
content:
application/json:
schema:
type: object
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: GetContact
summary: Get a Contact by ID
tags:
- Contacts
description: '**This endpoint returns the full details and all fields for the
specified contact**.
The "Get Contacts by Identifier" endpoint can be used to get the ID of a contact.'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ContactDetails3'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/batch:
post:
operationId: ListBatchedContact
summary: Get Batched Contacts by IDs
tags:
- Contacts
description: '**This endpoint is used to retrieve a set of contacts identified
by their IDs.**
This can be more efficient endpoint to get contacts than making a series of
individual `GET` requests to the "Get a Contact by ID" endpoint.
You can supply up to 100 IDs. Pass them into the `ids` field in your request
body as an array or one or more strings.
Twilio SendGrid recommends exporting your contacts regularly as a backup to
avoid issues or lost data.'
requestBody:
content:
application/json:
schema:
type: object
description: Array of IDs
properties:
ids:
maxItems: 100
type: array
items:
type: string
required:
- ids
example:
ids:
- '1234'
- '1235'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ContactDetails3'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
content:
application/json:
schema:
type: object
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/{contact_id}/identifiers:
delete:
operationId: DeleteContactIdentifier
summary: Delete a Contact Identifier
tags:
- Contacts
description: '**This endpoint can be used to delete one identifier from a contact.**
Deletion jobs are processed asynchronously.
Note this is different from deleting a contact. If the contact has only one
identifier, the asynchronous request will fail. All contacts are required
to have at least one identifier.
The request body field `identifier_type` must have a valid value of "EMAIL",
"PHONENUMBERID", "EXTERNALID", or "ANONYMOUSID".
'
parameters:
- name: contact_id
in: path
description: Must be set to the `contact_id` of the contact you want to remove
the identifier from.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
identifier_type:
type: string
description: The type of identifier you are removing from the contact.
$ref: '#/components/schemas/IdentifierType'
identifier_value:
type: string
description: The value of the identifier you want to remove from
the contact.
required:
- identifier_type
- identifier_value
example:
identifier_type: PHONENUMBERID
identifier_value: '15555555555'
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
description: Indicates that the deletion is queued for processing.
Check the job status with the Import Contacts Status endpoint.
properties:
job_id:
type: object
description: The deletion job ID.
required:
- job_id
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
required:
- errors
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/count:
get:
operationId: ListContactCount
summary: Get Total Contact Count
tags:
- Contacts
description: '**This endpoint returns the total number of contacts you have
stored.**
Twilio SendGrid recommends exporting your contacts regularly as a backup to
avoid issues or lost data.'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
contact_count:
type: integer
description: The total number of contacts.
billable_count:
type: integer
default: 0
description: The count of contacts this month for billing purposes.
minimum: 0
billable_breakdown:
type: object
description: '`billable_breakdown` will only appear to the parent
user in an account with subusers.'
properties:
total:
type: integer
description: The sum of all the subuser's billable contacts
breakdown:
type: object
description: A map of each subuser's billable contact usage.
Each key is the subuser's ID and each value is the usage
thus far this month.
minProperties: 0
required:
- contact_count
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/exports:
post:
operationId: ExportContact
summary: Export Contacts
tags:
- Contacts
description: '**Use this endpoint to export lists or segments of contacts**.
If you would just like to have a link to the exported list sent to your email
set the `notifications.email` option to `true` in the `POST` payload.
If you would like to download the list, take the `id` that is returned and
use the "Export Contacts Status" endpoint to get the `urls`. Once you have
the list of URLs, make a `GET` request to each URL provided to download your
CSV file(s).
You specify the segments and or/contact lists you wish to export by providing
the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields
in the request body.
The lists will be provided in either JSON or CSV files. To specify which of
these you would required, set the request body `file_type` field to `json`
or `csv`.
You can also specify a maximum file size (in MB). If the export file is larger
than this, it will be split into multiple files.'
requestBody:
content:
application/json:
schema:
type: object
properties:
list_ids:
description: IDs of the contact lists you want to export.
type: array
items:
type: string
format: uuid
segment_ids:
description: IDs of the contact segments you want to export.
type: array
items:
type: string
notifications:
type: object
properties:
email:
type: boolean
file_type:
type: string
description: File type for export file. Choose from `json` or `csv`.
default: csv
$ref: '#/components/schemas/FileType'
max_file_size:
description: The maximum size of an export file in MB. Note that
when this option is specified, multiple output files may be returned
from the export.
default: 5000
type: integer
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties:
_metadata:
$ref: '#/components/schemas/Metadata'
id:
type: string
description: The ID of the export job.
required:
- _metadata
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
get:
operationId: ListExportContact
summary: Get All Existing Exports
tags:
- Contacts
description: "**Use this endpoint to retrieve details of all current exported\
\ jobs**.\n\nIt will return an array of objects, each of which records an\
\ export job in flight or recently completed. \n\nEach object's `export_type`\
\ field will tell you which kind of export it is and its `status` field will\
\ indicate what stage of processing it has reached. Exports which are `ready`\
\ will be accompanied by a `urls` field which lists the URLs of the export's\
\ downloadable files \u2014 there will be more than one if you specified a\
\ maximum file size in your initial export request.\n\nUse this endpoint if\
\ you have exports in flight but do not know their IDs, which are required\
\ for the \"Export Contacts Status\" endpoint."
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
type: object
properties:
id:
type: string
description: Export jobs ID.
status:
type: string
description: 'Allowed values: `pending`, `ready`, or `failure`.'
created_at:
type: string
description: This ISO8601 timestamp when the export was
created.
completed_at:
type: string
description: This ISO8601 timestamp when the export was
completed.
expires_at:
type: string
description: This ISO8601 timestamp when the export expires.
urls:
type: array
description: One or more download URLs for the contact file(s)
if the status is `ready`.
items:
type: string
user_id:
type: string
description: User ID.
export_type:
type: string
description: 'Allowed types: `contacts_export`, `list_export`,
or `segment_export`.'
segments:
type: array
items:
type: object
properties:
ID:
type: string
Name:
type: string
lists:
type: array
items:
type: object
properties:
ID:
type: string
Name:
type: string
_metadata:
type: object
properties:
prev:
type: string
self:
type: string
next:
type: string
_metadata:
type: object
properties:
prev:
type: string
self:
type: string
description: Link to this page.
next:
type: string
description: Link to next page.
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
error_id:
type: string
required:
- message
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/exports/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: GetExportContact
summary: Export Contacts Status
tags:
- Contacts
description: "**This endpoint can be used to check the status of a contact export\
\ job**. \n\nTo use this call, you will need the `id` from the \"Export Contacts\"\
\ call.\n\nIf you would like to download a list, take the `id` that is returned\
\ from the \"Export Contacts\" endpoint and make an API request here to get\
\ the `urls`. Once you have the list of URLs, make a `GET` request on each\
\ URL to download your CSV file(s).\n\nTwilio SendGrid recommends exporting\
\ your contacts regularly as a backup to avoid issues or lost data."
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ContactExport'
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/imports:
put:
operationId: ImportContact
summary: Import Contacts
tags:
- Contacts
description: '**This endpoint allows a CSV upload containing up to one million
contacts or 5GB of data, whichever is smaller. At least one identifier is
required for a successful import.**
Imports take place asynchronously: the endpoint returns a URL (`upload_uri`)
and HTTP headers (`upload_headers`) which can subsequently be used to `PUT`
a file of contacts to be imported into our system.
Uploaded CSV files may also be [gzip-compressed](https://en.wikipedia.org/wiki/Gzip).
In either case, you must include the field `file_type` with the value `csv`
in your request body.
The `field_mappings` parameter is a respective list of field definition IDs
to map the uploaded CSV columns to. It allows you to use CSVs where one or
more columns are skipped (`null`) or remapped to the contact field.
For example, if `field_mappings` is set to `[null, "w1", "_rf1"]`, this means
skip column 0, map column 1 to the custom field with the ID `w1`, and map
column 2 to the reserved field with the ID `_rf1`. See the "Get All Field
Definitions" endpoint to fetch your custom and reserved field IDs to use with
`field_mappings`.
Once you receive the response body you can then initiate a **second** API
call where you use the supplied URL and HTTP header to upload your file. For
example:
`curl --upload-file "file/path.csv" "URL_GIVEN" -H "HEADER_GIVEN"`
If you would like to monitor the status of your import job, use the `job_id`
and the "Import Contacts Status" endpoint.
Twilio SendGrid recommends exporting your contacts regularly as a backup to
avoid issues or lost data.
'
requestBody:
content:
application/json:
schema:
type: object
properties:
list_ids:
type: array
description: All contacts will be added to each of the specified
lists.
items:
type: string
file_type:
type: string
description: Upload file type.
$ref: '#/components/schemas/FileType1'
field_mappings:
type: array
description: Import file header to reserved/custom field mapping.
uniqueItems: false
minItems: 1
items:
type: string
nullable: true
required:
- file_type
- field_mappings
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
description: The ID of the import job.
upload_uri:
type: string
description: The URI to PUT the upload file to.
upload_headers:
type: array
description: A list of headers that must be included in PUT request.
items:
type: object
properties:
header:
type: string
value:
type: string
required:
- header
- value
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ContactsError'
required:
- errors
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
content:
application/json:
schema:
type: object
description: If any of the specified lists do not exist.
properties:
errors:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ContactsError'
required:
- errors
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/imports/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: GetImportContact
summary: Import Contacts Status
tags:
- Contacts
description: "**This endpoint can be used to check the status of a contact import\
\ job**. \n\nUse the `job_id` from the \"Import Contacts,\" \"Add or Update\
\ a Contact,\" or \"Delete Contacts\" endpoints as the `id` in the path parameter.\n\
\nIf there is an error with your `PUT` request, download the `errors_url`\
\ file and open it to view more details.\n\nThe job `status` field indicates\
\ whether the job is `pending`, `completed`, `errored`, or `
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_mc_contacts_v3.yaml