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:

http://status.sendwithus.com


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