Overview
The Sendwithus API is based on the REST paradigm, and thus features resource based URLs with standard HTTP response codes to indicate errors. We use standard HTTP authentication and request verbs, and all responses are JSON formatted.
To make the integration process as easy as possible, we include test API keys with all accounts. Any requests made with test API keys will handle data and give responses, but not actually send any emails.
Base URL
All API URLs referenced in this document are relative to the following base URL:
https://api.sendwithus.com/api/v1
Authentication
The Sendwithus API uses HTTP Basic Authentication.
All requests require you to authenticate using a Sendwithus API Key as the username with an empty string as the password:
curl -u live_1234qwerzxcv7890: https://api.sendwithus.com/api/v1
All API calls must use HTTPS. Any calls made using HTTP will return an appropriate error code.
Errors
Any API request will receive a standard HTTP response code.
Response Ranges:
- 2xx -- Successful Request
- 4xx -- Failed Request (Client error)
- 5xx -- Failed Request (Server error)
Versioning
Any time we make backwards-incompatible changes to our API, we will release a new version. Our current API is v1, with v2 currently under development.
API Client Libraries
Sendwithus provides API Clients for all major languages and web frameworks. If we're missing a client for your particular use case, please let us know.
All of our API Client Libraries are open source and available in our Github Account.
Offical API Clients
Unofficial, Third-party API Clients
Sendwithus Status
Sendwithus' application and network status is available here:
Templates API
If no locale is specified in the URL the default locale will be used in all cases.
NOTE -- All parameters are mandatory unless otherwise noted.
Get a List of Templates
GET /templates
Sample Response:
[
{
"id": "Template ID",
"name": "Template Name",
"locale": "en-US",
"created": "created unix timestamp",
"versions": [
{
"name": "Version Name",
"id": "Version ID",
"published": true,
"created": "created unix timestamp",
"modified": "modified unix timestamp"
}
],
"tags": ["tag1", "tag2"]
}
]
Get a specific template (all versions)
GET /templates/(:template_id)
GET /templates/(:template_id)/locales/(:locale)
Sample Response:
{
"id": "tem_hQf1VnmCNrPjBdYQPOpLZ9",
"name": "Template Name",
"created": 1411606421,
"locale": "en-US",
"versions": [
{
"name": "Version Name",
"id": "ver_rmU8gMtRTYpwQcpYaPnB5p",
"published": true,
"created": "created unix timestamp",
"modified": "modified unix timestamp"
}
],
"tags": ["tag1", "tag2"]
}
Get a list of template versions (with HTML/text)
GET /templates/(:template_id)/versions
GET /templates/(:template_id)/locales/(:locale)/versions
Sample Response:
[
{
"id": "tem_hQf1VnmCNrPjBdYQPOpLZ9",
"created": 1411606421,
"modified": 1411610000,
"published": true,
"name": "Version 1",
"html": "<html>...</html>",
"text": "Hello World",
"subject": "My Subject"
},
{
"id": "tem_hQf1VnmCNrPjBdYQPOpLZ8",
"created": 1411606706,
"modified": 1411610000,
"published": false,
"name": "Version 2",
"html": "<html>...</html>",
"text": "Hello World Again",
"subject": "My Subject Again"
}
]
Get a specific version (with HTML/text)
GET /templates/(:template_id)/versions/(:version_id)
GET /templates/(:template_id)/locales/(:locale)/versions/(:version_id)
Sample Response:
{
"id": "tem_hQf1VnmCNrPjBdYQPOpLZ9",
"created": 1411606706,
"modified": 1411610000,
"published": true,
"name": "Version Name",
"html": "<html>...</html>",
"text": "Hello World",
"subject": "My Subject"
}
Update a Template Version
PUT /templates/(:template_id)/versions/(:version_id)
PUT /templates/(:template_id)/locales/(:locale)/versions/(:version_id)
Params:
- name -- The version name of the template
- subject -- The subject line of the template
- html (optional) -- The HTML body of the template
- text (optional) -- The Plain Text body of the template
NOTE -- At least one of html or text must be specified
NOTE -- This will replace the current version of the specified template
Sample Request:
{
"html": "<html><head></head><body><h1>UPDATE</h1></body></html>",
"name": "New Version",
"subject": "edited!",
"text": "sometext"
}
Sample Response:
{
"created": 1408394344,
"html": "<html><head></head><body><h1>UPDATE</h1></body></html>",
"id": "ver_RjEBErY6eXBPpgYt269iJU",
"name": "New Version",
"published": true,
"subject": "edited!",
"text": "sometext"
}
Create a New Template
POST /templates
Params:
- name -- The name of the template
- subject -- The subject line of the template
- html (optional) -- The HTML body of the template
- text (optional) -- The Plain Text body of the template
- locale (optional) -- The locale code of the template (defaults to en-US)
NOTE -- At least one of html or text must be specified
Sample Request:
{
"html": "<html><head></head><body><h1>NEW TEMPLATE</h1></body></html>",
"name": "New Template",
"subject": "This is a new template!",
"text": "some text"
}
Sample Response:
{
"id": "tem_ACdWZKZf4CtZNPM27WAdf6",
"locale": "en-US",
"name": "New Template"
}
Add Locale to Existing Template
POST /templates/(:template_id)/locales
Params:
- name -- The name of the initial version
- subject -- The subject line of the template
- locale -- The locale code of the new template
- html (optional) -- The HTML body of the template
- text (optional) -- The Plain Text body of the template
NOTE -- At least one of html or text must be specified
Sample Request:
{
"html": "<html><head></head><body><h1>Nouveau modèle!</h1></body></html>",
"name": "Published French Version",
"subject": "Ce est un nouveau modèle!",
"locale": "fr-FR",
"text": "un texte"
}
Sample Response:
{
"id": "tem_ACdWZKZf4CtZNPM27WAdf6",
"locale": "fr-FR",
"name": "A New Template",
"version_id": "ver_RjEBErY6eXBPpgYt269iJU"
}
Create a New Template Version
POST /templates/(:template_id)/versions
POST /templates/(:template_id)/locales/(:locale)/versions
Params:
- name -- The version name of the template
- subject -- The subject line of the template
- html (optional) -- The HTML body of the template
- text (optional) -- The Plain Text body of the template
NOTE -- At least one of html or text must be specified
Sample Request:
{
"html": "<html><head></head><body><h1>NEW TEMPLATE VERSION</h1></body></html>",
"name": "New Template Version",
"subject": "New Version!",
"text": "some text"
}
Sample Response:
{
"id": "ver_s6a68dJuz6Rn8dypq4j4Qo",
"created": 1410808743,
"modified": 1410808900,
"published": false,
"name": "New Template Version",
"html": "<html><head></head><body><h1>NEW TEMPLATE VERSION</h1></body></html>",
"text": "some text",
"subject": "New Version!"
}
Delete a specific template
DELETE /templates/(:template_id)
DELETE /templates/(:template_id)/locales/(:locale)
NOTE -- all versions and locales will be deleted unless a locale is specified
Sample Response:
{
"success": true,
"status": "OK"
}
Send API
NOTE -- All parameters are mandatory unless otherwise noted.
NOTE -- If a customer does not exist by the specified email, this call will create a customer.
Send an Email
POST /send
Params:
- template -- Template ID to send
- recipient
- address -- The recipient's email address
- name (optional) -- The recipient's name
- cc (optional) -- An array of CC recipients, of the format {"address":"cc@email.com"}
- bcc (optional) -- An array of BCC recipients, of the format {"address":"bcc@email.com"}
- sender (optional)
- address -- The sender's email address
- reply_to -- The sender's reply-to address
- name -- The sender's name
- template_data (optional) -- Object containing email template data (maximum 128KB)
- tags (optional) -- Array of tags (as strings). Tags are passed to your ESP as Categories, Tags, etc.
- headers (optional) -- Object contain SMTP headers to be included with the email
- inline (optional) -- Inline attachment object (see example)
- files (optional) -- List of file attachments (combined maximum 7MB, see example)
- esp_account (optional) -- ID of the ESP Account to send this email through. ex: esp_1a2b3c4d5e
- locale (optional) -- Template locale to send (ie: en-US)
- version_name (optional) -- Name of the template version to send (overrides A/B tests)
Sample Request:
{
"template": "tem_A5RHVP6CnRbS34UysLjYHx",
"recipient": {
"name": "John",
"address": "user@email.com"
},
"template_data": { "amount": "$12.00" },
"cc": [
{"address": "cc_one@email.com"},
{"address": "cc_two@email.com"}
],
"bcc": [
{"address": "bcc_one@email.com"},
{"address": "bcc_two@email.com"}
],
"sender": {
"name": "Company",
"address": "company@company.com",
"reply_to": "info@company.com"
},
"tags": [
"tag1",
"tag2",
"tag3"
],
"headers": {
"X-HEADER-ONE": "header-value"
},
"inline": {
"id": "cat.png",
"data": "{BASE_64_ENCODED_FILE_DATA}"
},
"files": [
{
"id": "doc.txt",
"data": "{BASE_64_ENCODED_FILE_DATA}"
},
{
"id": "stuff.zip",
"data": "{BASE_64_ENCODED_FILE_DATA}"
}
],
"locale": "en-US",
"esp_account": "esp_1a2b3c4d5e",
"version_name": "Version Name"
}
Sample Response:
{
"success": true,
"status": "OK",
"receipt_id": "log_asdf1234qwerty",
"email": {
"name": "NAME OF EMAIL",
"version_name": "NAME OF VERSION",
"locale": "en-US"
}
}
Inline Images
Sample Request Code
{
"template": "tem_9UPo9P7qMr8qHwHvPhDjP6F6f",
"recipient": {
"name": "John",
"address": "customer@example.com"
},
"inline": {
"id": "happy.png",
"data": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAMAAAC6V+0/AAAANlBMVEX1zHX///////70znj31I799eP20YP53qb879P879V/XjXTrWO5lFSgfUbYsWWOazx0Ui+DYjfNsfnyAAAAfUlEQVQYlXWQ2w6AIAxDK3KTIej//6yboiiZfWjGSZaVYlKE000MHvAhmg6dRZN1N1xmPJqXC7oXY+oEGouPrGEYZaq1e2QYZEipe2DoMcgzHBnwB2W90PWk0tblEG1ZWN6oHTojlT2ta9rLHamFp5yph1e/qReiV6eXPOoAcMkDL0/NWToAAAAASUVORK5CYII="
}
}
Sample Template Code
<img src="cid:happy.png" alt="a happy face">
Logs API
NOTE -- All parameters are mandatory unless otherwise noted.
Get a specific log + metadata
GET /logs/(:log_id)
A single Log object with all its details
Params:
- log_id -- String id of the Log to retrieve.
Sample Response:
{
"object": "log",
"id": "log_asdf1234qwerty",
"created": 1234567890,
"recipient_name": "Brad",
"recipient_address": "brad@email.com",
"status": "opened",
"message": "SendGrid: Message has been opened",
"email_id": "as8dfjha8dap",
"email_name": "Order Confirmation",
"email_version": "Version A"
}
Possible log.status values:
- requested: sendwithus API request received
- triggered: email triggered by internal event, ie*: drip campaign*
- queued: email is queued for delivery
- sent: email has successfully reached email service provider
- clicked: a link in the email has been clicked
- re_clicked: a link in the email has been clicked more than once
- opened: the email has been opened
- re_opened: the email has been opened more than once
- failed_to_queue: an internal error has temporarily prevented delivery
- failed_to_send: an email service provider error has temporarily prevented delivery
- processed: email service provider has acknowledged delivery request
- dropped: email service provider has prevented email delivery
- delivered: email was successfully delivered to recipient
- deferred: email service provider has delayed email delivery
- bounced: email service provider could not deliver to recipient
- reported_as_spam: recipient has reported the email as spam
- unsubscribed: recipient has requested to be unsubscribed from this email
Retrieve events for a specific log_id.
GET /logs/(:log_id)/events
Return a list of all events associated with a given Log.
Params:
- log_id (required) -- String id of the Log to retrieve events for.
Sample Response:
[
{
"object": "event",
"created": 1234567890,
"type": "requested",
"message": "requested"
},
{
"object": "event",
"created": 1234567891,
"type": "queued",
"message": "email queued"
},
{
"object": "event",
"created": 1234567892,
"type": "failed_to_send",
"message": "email failed to send, will retry"
},
{
"object": "event",
"created": 1234567893,
"type": "sent",
"message": "email sent through SendGrid"
},
{
"object": "event",
"created": 1234567894,
"type": "opened",
"message": "SendGrid: Email has been opened"
},
{
"object": "event",
"created": 1234567895,
"type": "clicked",
"message": "SendGrid: Link in email has been clicked"
}
]
Resend an existing Log
POST /resend
Resend a specific email by id.
Sample Request:
{
"log_id": "log_asdf123456qwerty"
}
Sample Response:
{
"success": true,
"status": "OK",
"receipt_id": "log_asdf123456qwerty",
"email": {
"name": "Order Confirmation",
"version_name": "Version A",
"locale": "en-US"
}
}
Snippets API
NOTE -- All parameters are mandatory unless otherwise noted.
Get all snippets
GET /snippets
Sample Response:
[
{
"object": "snippet",
"id": "snp_Q33jTLFc2ayG9KrF2Vcm4F",
"name": "My First Snippet",
"body": "<h1>Welcome!</h1>",
"created": 5858858124,
"modified": 5938868250
}
]
Get specific snippet
GET /snippets/(:id)
Sample Response:
{
"object": "snippet",
"id": "snp_Q33jTLFc2ayG9KrF2Vcm4F",
"name": "My First Snippet",
"body": "<h1>Welcome!</h1>",
"created": 5858858124,
"modified": 5938868250
}
Creating a new snippet
POST /snippets
Params:
- name -- Name of the snippet
- body -- Contents for the snippet
Sample Request:
{
"name": "My First Snippet",
"body": "<h1>Welcome!</h1>"
}
Sample Response:
{
"success": true,
"status": "OK",
"snippet": {
"object": "snippet",
"id": "snp_Q33jTLFc2ayG9KrF2Vcm4F",
"name": "My First Snippet",
"body": "<h1>Welcome!</h1>",
"created": 5858858124,
"modified": 5938868250
}
}
Update an existing snippet
PUT /snippets/(:id)
Params:
- name -- Name of the snippet
- body -- Contents for the snippet
Sample Request:
{
"name": "My First Snippet",
"body": "<h1>Welcome!</h1>"
}
Sample Response:
{
"success": true,
"status": "OK",
"snippet": {
"object": "snippet",
"id": "snp_Q33jTLFc2ayG9KrF2Vcm4F",
"name": "My First Snippet",
"body": "<h1>Welcome!</h1>",
"created": 5858858124,
"modified": 5938868250
}
}
Delete an existing snippet
DELETE /snippets/(:id)
Sample Response:
{
"success": true,
"status": "OK"
}
Render API
The render api allows you to render a template with data, using the exact same rendering workflow that Sendwithus uses when delivering your email.
NOTE -- All parameters are mandatory unless otherwise noted.
Render a Template with Data
POST /render
Params:
- template -- Template ID
- template_data -- Object containing email template data
- version_id (optional) -- Version ID obtained from /templates/(:template_id)/versions
- version_name (optional) -- Version name that you want rendered (provide either a version_name or a version_id, not both)
- locale (optional) -- Template locale to render
- strict (optional) -- Render in strict mode (fails on missing template data)
Sample Request:
{
"template": "tem_A5RHVP6CnRbS34UysLjYHx",
"template_data": { "amount": "$12.00" },
"version_id": "ver_r4nd0ml3tt3rsv15h4l0l",
"locale": "en-US",
"strict": true
}
Sample Response:
{
"success": true,
"status": "OK",
"template": {
"id": "ver_r4nd0ml3tt3rsv15h4l0l",
"name": "Template name",
"version_name": "Template version name",
"locale": "en-US"
},
"subject": "RENDERED SUBJECT WITH DATA",
"html": "RENDERED HTML BODY WITH DATA",
"text": "RENDERED TEXT BODY WITH DATA"
}
Customers API
NOTE -- All parameters are mandatory unless otherwise noted.
Get a Specific Customer
This call will retrieve a customer by a specified email.
GET /customers/customer@example.com
Sample Response:
{
"success": true,
"status": "OK",
"customer": {
"object": "customer",
"email": "customer@example.com",
"created": 5858858124,
"locale": "en-US"
}
}
Creating/Updating a New Customer
All parameters are mandatory unless otherwise noted.
POST /customers
Params:
- email -- Email (key) of the customer
- locale (optional) -- Specify a locale for this customer
Sample Request:
{
"email": "matt@sendwithus.com",
"locale": "de-DE"
}
Sample Response:
{
"success": true,
"status": "OK"
}
Delete a Customer
DELETE /customers/(:email)
NOTE -- Deleting customers will not remove any pending scheduled drip campaign emails. To prevent these emails from being delivered, you must deactivate the user using the Drip Campaign Deactivation endpoint.
Sample Response:
{
"success": true,
"status": "OK"
}
Get Email Logs for a Customer
This call will retrieve email logs for a customer.
GET /customers/matt@sendwithus.com/logs?count={count}&created_lt={timestamp}&created_gt={timestamp}
Arguments:
- count (optional) -- A number between 1 and 100 to specify the number of logs returned (including scheduled drips). If none is specified, a limit of 100 sent logs is automatically imposed.
- created_lt (optional) -- A Unix Timestamp used as a index for the search. The logs retrieved will have been sent before the timestamp specified.
- created_gt (optional) -- A Unix Timestamp used as a index for the search. The logs retrieved will have been sent after the timestamp specified.
Sample Response:
{
"success": true,
"status": "OK",
"logs": [
{
"object": "log",
"id": "log_asdf1234qwerty",
"created": 1234567890,
"recipient_name": "Matt",
"recipient_address": "matt@sendwithus.com",
"status": "opened",
"message": "SendGrid: Message has been opened",
"email_id": "tem_as8dfjha8dap",
"email_name": "Order Confirmation",
"email_version": "Version A"
},
{ ... },
{ ... }
]
}
Drip Campaigns API
Activate campaign for a customer
This will add the specified customer to the first step of the specified drip campaign. If the first step has a delay on it, then it will send the first email once that delay has elapsed.
POST /drip_campaigns/(:drip_campaign_id)/activate
Params:
- recipient
- address -- The recipient's email address
- name (optional) -- The recipient's name
- cc (optional) -- An array of CC recipients, of the format {"address":"cc@email.com"}
- bcc (optional) -- An array of BCC recipients, of the format {"address":"bcc@email.com"}
- sender (optional)
- address -- The sender's email address
- reply_to -- The sender's reply-to address
- name -- The sender's name
- email_data (optional) -- Object containing email template data
- tags (optional) -- Array of tags (as strings)
- headers (optional) -- Object contain SMTP headers to be included with the email
- esp_account (optional) -- ID of the ESP Account to send this email through. ex: esp_1a2b3c4d5e
- locale (optional) -- Locale to send emails with
Sample Request
{
"recipient": {
"address": "customer@example.com"
}
}
Sample Request with data
{
"recipient": {
"name": "John",
"address": "user@email.com"
},
"email_data": { "amount": "$12.00" },
"cc": [
{"address": "cc_one@email.com"},
{"address": "cc_two@email.com"}
],
"bcc": [
{"address": "bcc_one@email.com"},
{"address": "bcc_two@email.com"}
],
"sender": {
"name": "Company",
"address": "company@company.com",
"reply_to": "info@company.com"
},
"tags": [
"tag1",
"tag2",
"tag3"
],
"headers": {
"X-HEADER-ONE": "header-value"
},
"locale": "en-US",
"esp_account": "esp_1a2b3c4d5e"
}
Sample Response
{
"success": true,
"status": "OK",
"drip_campaign": {
"id": "dc_m3mfMgMiemni82nm2imGMw",
"name": "welcome_campaign"
},
"recipient_address": "customer@example.com",
"message": "Recipient successfully added to drip campaign."
}
Deactivate a campaign for customer
POST /drip_campaigns/(:drip_campaign_id)/deactivate
Params:
- recipient_address -- Email address of the customer you would like to remove from the specified campaign.
Sample Request
{
"recipient_address": "customer@example.com"
}
Sample Response
{
"success": true,
"status": "OK",
"drip_campaign": {
"id": "dc_m3mfMgMiemni82nm2imGMw",
"name": "welcome_campaign"
},
"recipient_address": "customer@example.com",
"message": "Recipient successfully removed from drip campaign."
}
Deactivate a customer from all campaigns
If a user unsubscribes, changes email addresses, or cancels, call this endpoint to remove the specified email address from all active drip campaigns.
POST /drip_campaigns/deactivate
Params:
- recipient_address -- Email address of the customer you would like to remove from all drip campaigns.
Sample Request
{
"recipient_address": "customer@example.com"
}
Sample Response
{
"success": true,
"status": "OK",
"recipient_address": "customer@example.com"
}
Get a list of campaigns
GET /drip_campaigns
Sample Response
[
{
"object": "drip_campaign",
"id": "dc_m3mfMgMiemni82nm2imGMw",
"name": "welcome_campaign",
"enabled": true,
"trigger_email_id": null,
"drip_steps": [
{
"object": "drip_step",
"id": "dcs_MEitnqi2mGmwiednWN2mwi",
"email_id": "tem_asdfjkl1234qwer",
"delay_seconds": "600"
},
{
"object": "drip_step",
"id": "dcs_MEitn234mGmwiednWN2mwi",
"email_id": "tem_asdwtgs1234qwer",
"delay_seconds": "3600"
}
]
},
{
"object": "drip_campaign",
"id": "dc_m3mfMgafasdi8gadbwEgv",
"name": "sales_campaign",
"enabled": true,
"trigger_email_id": "tem_wneiam3igmiocbmw",
"drip_steps": [
{
"object": "drip_step",
"id": "dcs_MEitnf2egbDwiednWN2mwi",
"email_id": "tem_asdwGFWrb234qwer",
"delay_seconds": "7200"
}
]
}
]
Get the details on a specific drip campaign
GET /drip_campaigns/(:drip_campaign_id)
Sample Response
{
"object": "drip_campaign",
"id": "dc_m3mfMgMiemni82nm2imGMw",
"name": "welcome_campaign",
"enabled": true,
"trigger_email_id": null,
"drip_steps": [
{
"object": "drip_step",
"id": "dcs_MEitnqi2mGmwiednWN2mwi",
"email_id": "tem_asdfjkl1234qwer",
"delay_seconds": "600"
},
{
"object": "drip_step",
"id": "dcs_MEitn234mGmwiednWN2mwi",
"email_id": "tem_asdwtgs1234qwer",
"delay_seconds": "3600"
}
]
}
Internationalization (i18n) API
How it works
Sendwithus handles internationalization by using Jinja2 style trans blocks.
The easiest way to set up templates for translation is to use the trans block syntax. A string can be marked for translation by simply wrapping it in a trans block. For example, the internationalized version of "Hello World" is "{% trans %}Hello World{% endtrans %}".
Variables in trans block can be added like normal template variables. For example "Hello {{ name }}" will become "{% trans %}Hello {{ name }}{% endtrans %}". Multiple variables can be used in the same trans block.
Translation packages (.pot files) can be downloaded via API, and then corresponding string files (.po) can be uploaded via API, which will trigger translated template variants to be generated.
Get translation package (.pot file)
This call will fetch a .pot translation package for all templates that have been assigned the corresponding tag.
GET /i18n/pot/(:tag)
Params:
- tag -- String will return a .pot file only for templates that have the corresponding tag. Tags can be set via the Sendwithus dashboard.
Examples
Fetch .pot for template with tag "international".
GET /i18n/pot/international
Sample Response:
The reponse is a valid .pot file.
msgid "Welcome to Sendwithus, %(first_name)s!"
msgstr ""
msgid "Confirm your email"
msgstr ""
Post translated strings and .po files
Use this endpoint to POST a .zip file containing .po files. Each .po file should be named to match the locale it is intended for. See examples below for specifics.
POST /i18n/po/(:tag)
Params:
- tag -- String of tag; templates with that tag applied will have a locale generated for each .po file in the .zip file
Request Body:
- .zip file
Examples
Example .zip structure:
translations.zip
├── fr-FR.po
└── ja-JP.po
Post translations.zip for templates with tag "international".
POST /i18n/po/international
Sample Response:
{}
Sending translated templates
At send time, Sendwithus uses the locale parameter in the Send API, and matches it against the template version for that locale. This is why .po files must have a filename that matches the locale.
For an example sending with a translated template, please see the send API documentation.
Locale Code Standards
We follow the IETF Language Tag standard which consists of a 2 character language code and a 2 character country code separated by a hyphen. Example: 'en-US' is the code for English (United States)
IETF Language Tags: http://en.wikipedia.org/wiki/IETF_language_tag
The prefix, in this case 'en', is a language code following the ISO 639-1 standard.
ISO 639-1: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
The suffix, in this case 'US', is a country code following the ISO 3166-1 Alpha-2 standard.
ISO 3166-1 Alpha-2: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
The Locale codes that we currently support are as follows:
en-US => English (United States)
af-ZA => Afrikaans (South Africa)
am-ET => Amharic (Ethiopia)
ar-AE => Arabic (UAE)
ar-BH => Arabic (Bahrain)
ar-DZ => Arabic (Algeria)
ar-EG => Arabic (Egypt)
ar-JO => Arabic (Jordan)
ar-KW => Arabic (Kuwait)
ar-LB => Arabic (Lebanon)
ar-MA => Arabic (Morocco)
ar-OM => Arabic (Oman)
ar-QA => Arabic (Qatar)
ar-SA => Arabic (Saudi Arabia)
ar-SD => Arabic (Sudan)
az-AZ => Azerbaijani (Azerbaijan)
be-BY => Belarusian (Belarus)
bg-BG => Bulgarian (Bulgaria)
bn-BD => Bengali (Bangladesh)
bn-MY => Bengali (Malaysia)
ca-ES => Catalan (Spain)
cs-CZ => Czech (Czech Republic)
da-DK => Danish (Denmark)
de-AT => German (Austria)
de-BE => German (Belgium)
de-CH => German (Switzerland)
de-DE => German (Germany)
de-LI => German (Liechtenstein)
de-LU => German (Luxembourg)
el-CY => Greek (Cyprus)
el-GR => Greek (Greece)
en-AE => English (UAE)
en-AL => English (Albania)
en-AM => English (Armenia)
en-AO => English (Angola)
en-AR => English (Argentina)
en-AT => English (Austrian)
en-AU => English (Australia)
en-AZ => English (Azerbaijan)
en-BB => English (Barbados)
en-BD => English (Bangladesh)
en-BE => English (Belgium)
en-BG => English (Bulgaria)
en-BH => English (Bahrain)
en-BO => English (Bolivia)
en-BR => English (Brazil)
en-BS => English (Bahamas)
en-BW => English (Botswana)
en-CA => English (Canada)
en-CH => English (Switzerland)
en-CL => English (Chile)
en-CN => English (China)
en-CO => English (Columbia)
en-CR => English (Costa Rica)
en-CY => English (Cyprus)
en-CZ => English (Czech Republic)
en-DE => English (Germany)
en-DK => English (Denmark)
en-DO => English (Dominican Republic)
en-DZ => English (Algeria)
en-EC => English (Ecuador)
en-EE => English (Estonia)
en-EG => English (Egypt)
en-ES => English (Spain)
en-ET => English (Ethiopia)
en-FI => English (Finland)
en-FR => English (France)
en-GB => English (Great Britain)
en-GH => English (Ghana)
en-GI => English (Gibraltar)
en-GR => English (Greece)
en-GT => English (Guatemala)
en-HK => English (Hong Kong)
en-HN => English (Honduras)
en-HR => English (Croatia)
en-HU => English (Hungary)
en-ID => English (Indonesia)
en-IE => English (Ireland)
en-IL => English (Israel)
en-IN => English (India)
en-IS => English (Iceland)
en-IT => English (Italy)
en-JM => English (Jamaica)
en-JO => English (Jordan)
en-JP => English (Japan)
en-KE => English (Kenya)
en-KH => English (Cambodia)
en-KR => English (Kuwait)
en-KW => English (Korean)
en-KZ => English (Kazakhstan)
en-LA => English (Laos)
en-LB => English (Lebanon)
en-LK => English (Sri Lanka)
en-LT => English (Lithuania)
en-LU => English (Luxembourg)
en-LV => English (Latvia)
en-MA => English (Morocco)
en-MC => English (Monaco)
en-MD => English (Moldova)
en-MM => English (Myanmar)
en-MN => English (Mongolia)
en-MX => English (Mexico)
en-MY => English (Malaysia)
en-NG => English (Nigeria)
en-NL => English (Netherlands)
en-NO => English (Norway)
en-NP => English (Nepal)
en-NZ => English (New Zealand)
en-OM => English (Oman)
en-PA => English (Panama)
en-PE => English (Peru)
en-PH => English (Philippines)
en-PK => English (Pakistan)
en-PL => English (Poland)
en-PT => English (Portugal)
en-PY => English (Paraguay)
en-QA => English (Qatar)
en-RO => English (Romania)
en-RS => English (Serbia)
en-RU => English (Russia)
en-SA => English (Saudi Arabia)
en-SD => English (Sudan)
en-SE => English (Sweden)
en-SG => English (Singapore)
en-SI => English (Slovenia)
en-SK => English (Slovakia)
en-SV => English (El Salvador)
en-TH => English (Thailand)
en-TR => English (Turkey)
en-TT => English (Trinidad and Tobago)
en-TW => English (Taiwan)
en-UY => English (Uruguay)
en-UZ => English (Uzbekistan)
en-VN => English (Vietnam)
en-ZA => English (South Africa)
es-AR => Spanish (Argentina)
es-BO => Spanish (Bolivia)
es-CL => Spanish (Chile)
es-CO => Spanish (Colombia)
es-CR => Spanish (Costa Rica)
es-DO => Spanish (Dominican Republic)
es-EC => Spanish (Ecuador)
es-ES => Spanish (Spain)
es-GT => Spanish (Guatemala)
es-HN => Spanish (Honduras)
es-LA => Spanish (Latin America)
es-MX => Spanish (Mexico)
es-PA => Spanish (Panama)
es-PE => Spanish (Peru)
es-PY => Spanish (Paraguay)
es-SV => Spanish (El Salvador)
es-US => Spanish (United States)
es-UY => Spanish (Uruguay)
es-VE => Spanish (Venezuela)
et-EE => Estonian (Estonia)
fi-FI => Finnish (Finland)
fr-BE => French (Belgium)
fr-CA => French (Canada)
fr-CD => French (Congo)
fr-CH => French (Switzerland)
fr-CI => French (Cote d'Ivoire)
fr-CL => French (Chile)
fr-CM => French (Cameroon)
fr-FR => French (France)
fr-GF => French (French Guiana)
fr-LB => French (Lebanon)
fr-LU => French (Luxembourg)
fr-MA => French (Morocco)
fr-MC => French (Monaco)
he-IL => Hebrew (Israel)
hi-IN => Hindi (India)
hr-HR => Croatian (Croatia)
hu-HU => Hungarian (Hungary)
hy-AM => Armenian (Armenia)
id-ID => Indonesian (Indonesia)
id-MY => Indonesian (Malaysia)
is-IS => Icelandic (Iceland)
it-CH => Italian (Switzerland)
it-IT => Italian (Italy)
it-MC => Italian (Monaco)
ja-JP => Japanese (Japan)
ka-GE => Georgian (Georgia)
kk-KZ => Kazakh (Kazakhstan)
km-KH => Khmer (Cambodia)
ko-KR => Korean (Korea)
lb-LU => Latvian (Latvia)
lo-LA => Laotian (Laos)
lt-LT => Luxembourgish (Luxembourg)
lv-LV => Lithuanian (Lithuania)
mk-MK => Macedonian (North Macedonia)
mn-MN => Mongolian (Myanmar)
ms-MY => Malay (Malaysia)
my-MM => Mongolian (Mongolia)
nb-NO => Norwegian Bokmal (Norway)
ne-MY => Nepali (Malaysia)
ne-NP => Nepali (Nepal)
nl-BE => Dutch (Belgium)
nl-NL => Dutch (Netherlands)
nl-SR => Dutch (Suriname)
nn-NO => Norwegian Nynorsk (Norway)
no-NO => Norwegian (Norway)
pl-GB => Polish (Great Britain)
pl-PL => Polish (Poland)
ps-AF => Pashto (Afghanistan)
pt-AO => Portuguese (Angola)
pt-BR => Portuguese (Brazil)
pt-PT => Portuguese (Portugal)
ro-MD => Romanian (Moldova)
ro-RO => Romanian (Romania)
ru-KZ => Russian (Kazakhstan)
ru-RU => Russian (Russia)
si-LK => Sinhala (Sri Lanka)
sk-SK => Slovak (Slovakia)
sl-SI => Slovenian (Slovenia)
sq-AL => Albanian (Albania)
sr-RS => Serbian (Serbia)
sv-SE => Swedish (Sweden)
sw-KE => Swahili (Kenya)
ta-LK => Tamil (Sri Lanka)
th-AU => Thai (Australia)
th-NZ => Thai (New Zealand)
th-TH => Thai (Thailand)
tl-AU => Tagalog (Australia)
tl-NZ => Tagalog (New Zealand)
tl-PH => Tagalog (Philippines)
tr-CY => Turkish (Cyprus)
tr-TR => Turkish (Turkey)
uk-UA => Ukrainian (Ukraine)
ur-PK => Urdu (Pakistan)
uz-UZ => Uzbek (Uzbekistan)
vi-AU => Vietnamese (Australia)
vi-CA => Vietnamese (Canada)
vi-NZ => Vietnamese (New Zealand)
vi-US => Vietnamese (United States)
vi-VN => Vietnamese (Vietnam)
zh-CN => Chinese (China)
zh-HK => Chinese (Hong Kong)
zh-TW => Chinese (Taiwan)
Batch API
The Sendwithus batch endpoint enables multiple API calls to be made in a single HTTP request.
NOTE -- Batch sizes over 10 requests are not recommended.
Sample Batch (Multiple Sends)
POST /batch
Params:
- path -- API path to call
- method -- HTTP method to use
- body -- HTTP request body
Sample Request:
[{
"path": "/api/v1/send",
"method": "POST",
"body": {
"template": "tem_QszsrasQP6nqGewZhKB2G",
"recipient": {
"address": "test+1@mydomain.com"
}
}
}, {
"path": "/api/v1/send",
"method": "POST",
"body": {
"template": "tem_doesntexist",
"recipient": {
"address": "test+2@mydomain.com"
}
}
}]
Sample Response:
NOTE -- Responses are returned in the same order as requested.
[{
"path": "/api/v1/send",
"status_code": 200,
"method": "POST",
"body": {
"success": true,
"email": {
"name": "Docs Page Curl Command",
"version_name": "Original"
},
"receipt_id": "log_asdf1234qwerty",
"status": "OK"
}
}, {
"path": "/api/v1/send",
"status_code": 400,
"method": "POST",
"body": "Template not found"
}]