> ## Documentation Index
> Fetch the complete documentation index at: https://platform.tatango.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating a New List
> This endpoint creates a new list.
Note: the following settings cannot be modified via the API:
* API Confirmation Resend Block Timeout
* Resubscribers
### FAQs
**What are the limitations for a keyword?**
* A keyword must contain at least two characters and no more than 15 characters.
* Keywords are not case sensitive. `FOO` will match `foo`, `FOO`, and `Foo`.
* You can't use obscene words. We're not going to spell them out here.
**Are keywords case sensitive?**
* No. The system checks for duplicate keywords by transforming all keywords to uppercase before performing matching algorithms.
**What happens if the keyword isn't available?**
* The response from the API will be a 422 error with the response body looking like this:
```json theme={null}
{"status":"error","error":"invalid keyword names: EXISTINGKW"}
```
**Can I check if a keyword is available?**
* Yes. By utilizing this endpoint. The response will either be:
```json theme={null}
{"status":"OK","keyword_name":"available"}
```
or
```json theme={null}
{"status":"OK","keyword_name":"unavailable","error":"Name is in use"}
```
**Can I add multiple keywords to a list?**
* Yes. The `keyword_names` parameter would need to be an array, like this:
```json theme={null}
{"keyword_names":["TEST","KEYWORD","NAMES"]}
```
**What is a REPLY Response?**
* REPLY Response is the response sent to the subscriber if they respond to the message with the word `REPLY`.
## Request URL
```http theme={null}
POST https://app.tatango.com/api/v2/lists/
```
## OpenAPI
````yaml POST /api/v2/lists/
openapi: 3.1.0
info:
title: Tatango Legacy v2 API
description: Tatango legacy v2 API endpoints for existing integrations.
version: 2.0.0
servers:
- url: https://app.tatango.com
security:
- basicAuth: []
paths:
/api/v2/lists/:
post:
tags:
- Lists
summary: Create a New List
description: This endpoint creates a new list.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateListRequest'
responses:
'200':
description: List created
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: List created
list:
$ref: '#/components/schemas/List'
required:
- status
- list
example:
status: List created
list:
id: 11
name: My awesome list
email_digest: myemail18@gmail.com
email_subscribe: true
email_unsubscribe: true
first_optin_message: >-
ACME Retail: You already agreed to recurring SMS/MMS msgs.
Txt STOP 2 end, HELP 4 help. Msg & data rates may apply.
Terms apply 12345-info.com
second_optin_message: >-
ACME Retail: Welcome back! You agreed to receive recurring
SMS/MMS msgs. Txt STOP 2 end, HELP 4 help. Msg&data rates
may apply. Terms apply 12345-info.com
message_help: >-
ACME Retail: Recurring SMS/MMS msgs. Text STOP 2 end.
Msg&data rates may apply. Terms apply 12345-info.com. Msging
help: help@12345-info.com
message_stop: >-
ACME Retail: You have been unsubscribed and will not receive
any more messages.
message_reply: >-
ACME Retail: Thank you for your response. Reply STOP to end,
HELP for help. Msg&data rates may apply. Terms apply
12345-info.com
message_already_subscribed: >-
ACME Retail: Reply YES for recurring autodialed SMS/MMS
marketing msgs. No purchase rqd. Msg&data rates may apply.
Terms apply 12345-info.com
message_yes: >-
ACME Retail: Recurring SMS/MMS msgs. Text STOP 2 end.
Msg&data rates may apply. Terms apply 12345-info.com. Msging
help: help@12345-info.com
keyword_names:
- JOIN
- SAVE
- COUPONS
- SALE
counts:
subscribers: 0
unsubscribed: 0
cleaned: 0
opt_in_type: single
opt_in_requests: []
x-codeSamples:
- lang: cURL
label: cURL
source: >-
curl "https://app.tatango.com/api/v2/lists/" -d '{"list":{"name":"My
awesome list","message_yes":"ACME Retail: Reply YES for recurring
autodialed SMS/MMS marketing msgs. No purchase rqd. Msg&data rates
may apply. Terms apply 12345-info.com","message_help":"ACME Retail:
Recurring SMS/MMS msgs. Text STOP 2 end. Msg&data rates may apply.
Terms apply 12345-info.com","message_stop":"ACME Retail: You have
been unsubscribed and will not receive any more
messages.","message_reply":"ACME Retail: Thank you for your
response. Reply STOP to end, HELP for help. Msg&data rates may
apply. Terms apply
12345-info.com","message_already_subscribed":"ACME Retail: You
already agreed to recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4
help. Msg&data rates may apply. Terms apply
12345-info.com","first_optin_message":"ACME Retail: You agreed to
receive recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4 help.
Msg&data rates may apply. Terms apply
12345-info.com","second_optin_message":"ACME Retail: Welcome back!
You agreed to receive recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4
help. Msg&data rates may apply. Terms apply
12345-info.com","email_digest":"myemail18@gmail.com","email_subscribe":true,"email_unsubscribe":true}}'
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u emailaddress@mydomain.com:my_api_key \
-H "Host: example.org" \
-H "Cookie: "
- lang: Ruby
label: Ruby
source: >-
require 'net/http'
require 'uri'
uri = URI.parse('https://app.tatango.com/api/v2/lists/')
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_url)
request.basic_auth("emailaddress@mydomain.com", "my_api_key")
request.body({"list":{"name":"My awesome list","message_yes":"ACME
Retail: Reply YES for recurring autodialed SMS/MMS marketing msgs.
No purchase rqd. Msg&data rates may apply. Terms apply
12345-info.com","message_help":"ACME Retail: Recurring SMS/MMS msgs.
Text STOP 2 end. Msg&data rates may apply. Terms apply
12345-info.com","message_stop":"ACME Retail: You have been
unsubscribed and will not receive any more
messages.","message_reply":"ACME Retail: Thank you for your
response. Reply STOP to end, HELP for help. Msg&data rates may
apply. Terms apply
12345-info.com","message_already_subscribed":"ACME Retail: You
already agreed to recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4
help. Msg&data rates may apply. Terms apply
12345-info.com","first_optin_message":"ACME Retail: You agreed to
receive recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4 help.
Msg&data rates may apply. Terms apply
12345-info.com","second_optin_message":"ACME Retail: Welcome back!
You agreed to receive recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4
help. Msg&data rates may apply. Terms apply
12345-info.com","email_digest":"myemail18@gmail.com","email_subscribe":true,"email_unsubscribe":true}})\nresponse
= http.request(request)
- lang: JavaScript
label: JavaScript
source: >-
var request = new XMLHttpRequest();
request.open('POST', 'https://app.tatango.com/api/v2/lists/',
false);
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Basic ' +
btoa('emailaddress@mydomain.com:my_api_key'));
var data = JSON.stringify({
list: {
name: 'My awesome list',
message_yes: 'ACME Retail: Reply YES for recurring autodialed SMS/MMS marketing msgs. No purchase rqd. Msg&data rates may apply. Terms apply 12345-info.com',
message_help: 'ACME Retail: Recurring SMS/MMS msgs. Text STOP 2 end. Msg&data rates may apply. Terms apply 12345-info.com',
message_stop: 'ACME Retail: You have been unsubscribed and will not receive any more messages.',
message_reply: 'ACME Retail: Thank you for your response. Reply STOP to end, HELP for help. Msg&data rates may apply. Terms apply 12345-info.com',
message_already_subscribed: 'ACME Retail: You already agreed to recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4 help. Msg&data rates may apply. Terms apply 12345-info.com',
first_optin_message: 'ACME Retail: You agreed to receive recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4 help. Msg&data rates may apply. Terms apply 12345-info.com',
second_optin_message: 'ACME Retail: Welcome back! You agreed to receive recurring SMS/MMS msgs. Txt STOP 2 end, HELP 4 help. Msg&data rates may apply. Terms apply 12345-info.com',
email_digest: 'myemail18@gmail.com',
email_subscribe: true,
email_unsubscribe: true
}
});
request.send(data);
components:
schemas:
CreateListRequest:
type: object
properties:
list:
type: object
properties:
name:
type: string
description: >-
List names are to help you distinguish which list is which, and
are only visible to you, and are never seen by users. (Limit 25
characters)
example: My awesome list
message_yes:
type: string
description: >-
This message is sent to a user when their mobile number is added
to a list through the API. Users must respond "YES" or "Y" to
this message, to be subscribed.
example: >-
ACME Retail: Reply YES for recurring autodialed SMS/MMS
marketing msgs. No purchase rqd. Msg&data rates may apply. Terms
apply 12345-info.com
message_help:
type: string
description: >-
This is the message that is sent back to users when they respond
to any of your messages with the word "HELP".
example: >-
ACME Retail: Recurring SMS/MMS msgs. Text STOP 2 end. Msg&data
rates may apply. Terms apply 12345-info.com. Msging help:
help@12345-info.com
message_stop:
type: string
description: >-
This is the message that is sent back to users when they respond
to any of your messages with the word "STOP".
example: >-
ACME Retail: You have been unsubscribed and will not receive any
more messages.
message_reply:
type: string
description: >-
This is the message that is sent back to subscribers when they
respond to a mass message that you send them.
example: >-
ACME Retail: Thank you for your response. Reply STOP to end,
HELP for help. Msg&data rates may apply. Terms apply
12345-info.com
message_already_subscribed:
type: string
description: >-
This is the message that is sent back to users when they're
attempting to opt-in, but they're already subscribed to the
list.
example: >-
ACME Retail: You already agreed to recurring SMS/MMS msgs. Txt
STOP 2 end, HELP 4 help. Msg&data rates may apply. Terms apply
12345-info.com
first_optin_message:
type: string
description: >-
This message is sent to a phone number after they've
successfully completed the opt-in process for a specific list,
and at no point in the past has been subscribed to the list.
example: >-
ACME Retail: You agreed to receive recurring SMS/MMS msgs. Txt
STOP 2 end, HELP 4 help. Msg&data rates may apply. Terms apply
12345-info.com
second_optin_message:
type: string
description: >-
This message is sent to a phone number after they've
successfully completed the opt-in process for a specific list,
and at some point in the past has been subscribed to the list.
example: >-
ACME Retail: Welcome back! You agreed to receive recurring
SMS/MMS msgs. Txt STOP 2 end, HELP 4 help. Msg&data rates may
apply. Terms apply 12345-info.com
email_digest:
type: string
nullable: true
description: >-
Receive a daily email with a list of phone numbers that
subscribed and unsubscribed from a designated list. Leave blank
if you dont want to receive this daily email.
email_subscribe:
type: boolean
description: >-
Receive an email immediately when you get a new subscriber for a
designated list. Email contains phone number of new subscriber.
Leave blank if you dont want to receive this email.
example: true
email_unsubscribe:
type: boolean
description: >-
Receive an email immediately when a subscriber unsubscribes from
a designated list. Email contains phone number of lost
subscriber. Leave blank if you dont want to receive this email.
example: true
keyword_names:
type: array
items:
type: string
description: >-
(Optional) An array of keywords to associate to the list. See
the FAQs for keyword limitations.
required:
- name
required:
- list
List:
type: object
properties:
id:
type: integer
example: 7
name:
type: string
example: Mobile Campaign
email_digest:
type: string
example: myemail12@gmail.com
nullable: true
email_subscribe:
type: string
nullable: true
email_unsubscribe:
type: string
nullable: true
first_optin_message:
type: string
example: ''
second_optin_message:
type: string
example: ''
message_help:
type: string
nullable: true
message_stop:
type: string
nullable: true
message_reply:
type: string
nullable: true
message_already_subscribed:
type: string
nullable: true
message_yes:
type: string
nullable: true
keyword_names:
type: array
items:
type: string
counts:
$ref: '#/components/schemas/ListCounts'
opt_in_type:
type: string
example: single
opt_in_requests:
type: array
items:
type: object
required:
- id
- name
- keyword_names
- counts
- opt_in_type
ListCounts:
type: object
properties:
subscribers:
type: integer
example: 0
unsubscribed:
type: integer
example: 0
cleaned:
type: integer
example: 0
required:
- subscribers
- unsubscribed
- cleaned
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Tatango authenticates API requests by validating an API key passed via
HTTP Basic Authentication. Use your login email as the username and your
API key as the password.
````