# API Reference

Every API call in SENDUNE is a simple, language agnostic, cURL request.

SENDUNE does not publish integration libraries for any programming languages. You do not have to embed or update or maintain any of our code within your code. This is in line with our [first principles](https://docs.sendune.com/why).

### Base URL

```
https://api.sendune.com
```

The Base URL is followed by the endpoint you wish to call. Every API call must include the relevant 'secret key'. The base URL accepts only **HTTPS** traffic. **HTTP** is rejected. 

## There are four API endpoints.

### 1. Contacts API

The '**add-contact**' endpoint is is used to add/update contacts.

{% tabs %}
{% tab title="API Request" %}

<pre><code><strong>https://api.sendune.com/add-contact
</strong></code></pre>

```
 {
      "method": "POST",
      "url": "https://api.sendune.com/add-contact",
      "headers": {"template-key": "*****************************zkLG"},
      "body": {
          "email": "example@gmail.com",
          "status": "Unsubscribe",
          "full_name": "John Due",
          "mobile": "+918098763849",
          "dob": "10-10-1990",
          "gender": "Male",
          "city": "Hyderabad",
          "country": "India",
          "add_tags": "aaa,bbb,ccc",
          "remove_tags": "ddd,eee,fff"
      }
 }
```

**IMPORTANT:**

* The API call MUST include the **Contact Upload Secret Key**.
* The API call MUST include the '**Primary Key**' of the contact. Primary Key is used to uniquely identify a contact in the database. This is either the Email or the Mobile Number of your end user.
* Mobile numbers must strictly be in [<mark style="color:red;">**E.164**</mark>](https://help.twilio.com/articles/223183008-Formatting-International-Phone-Numbers) format. (Example: +442071838750).
  {% endtab %}

{% tab title="API Response" %}
Success Response:

{% code lineNumbers="true" %}

```
 {
      "success": true,
      "message": "Contact added"
 }
```

{% endcode %}

Failed Response:

{% code lineNumbers="true" %}

```
 {
      "success": false,
      "message": "message details",
      "error": "error details"
 }
```

{% endcode %}
{% endtab %}
{% endtabs %}

### 2. Email API

The '**send-email**' endpoint is used to send transactional emails. Every email template you create comes with a 'Template Key' which must be used in the cURL request.

{% tabs %}
{% tab title="API Request" %}

<pre><code><strong>https://api.sendune.com/send-email
</strong></code></pre>

{% code lineNumbers="true" %}

```
{
      "method": "POST",
      "url": "https://api.sendune.com/send-email",
      "headers": {"template-key": "***********************HOcm"},
      "body": {
          "email": "example@gmail.com",
          "subject": "Subject",
          "replace-tag": "Value"
       }
}
```

{% endcode %}

**IMPORTANT:**

* The API call MUST include the **Template Key**.&#x20;
* Template Key is unique to each email template you create.
* Template keys are secrets and must not be used on the client side.
  {% endtab %}

{% tab title="API Response" %}
Success Response:

{% code lineNumbers="true" %}

```
{
      "success": true,
      "message": "Email Sent"
}
```

{% endcode %}

Failed Response:

{% code lineNumbers="true" %}

```
{
      "success": false,
      "message": "message details",
      "error": "error details"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Rate Limits

Rate limits apply only to the Contacts API (add-contact) endpoint as per the below table.

<table data-full-width="false"><thead><tr><th width="225.5">Plan</th><th>Rate Limit (requests/minute)</th></tr></thead><tbody><tr><td>Free</td><td>60</td></tr><tr><td>Paid</td><td>1,800 (Soft Limit)</td></tr><tr><td>Enterprise</td><td>Upto 60,000</td></tr></tbody></table>

To illustrate, the 'Paid Plan' has a rate limit of 1800 requests/minute. This lets you call the SENDUNE Contacts API 30 times per second or do a single burst of 1800 calls in one second or anywhere in between. The sum total of all API calls must not exceed 1800 in one minute.

API rate limit is a soft limit for paid plans, meaning you can do occasional short bursts that exceed the rate limit as long as you are not abusing our systems.

{% hint style="success" %}
**IMPORTANT NOTE**

API rate limits do not apply to the Emails.

Email sending rates are determined by AWS. For example, if your AWS SES email sending rate is 250/second, you can call the '**send-email**' endpoint up to 250 times per second - even if you are on the 'Free Plan'.
{% endhint %}