> For the complete documentation index, see [llms.txt](https://maildrip.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://maildrip.gitbook.io/documentation/developers/getting-started.md).

# Getting Started

**1. Authentication** 

Before you can start making requests to the Maildrip API, you'll need to authenticate your API calls. Authentication ensures that only authorized users can access the Maildrip services.

**API Key Authentication**:

* Maildrip uses API key-based authentication. You must include your API key in the headers of your HTTP requests to authenticate.
* Your API key can be found in your Maildrip account settings under the "API Keys" section. Keep your API key secure and do not share it publicly.

**Example Header**:

```http
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json
```

**Sample cURL Request**:

```bash
curl -X GET "https://api.maildrip.io/v1/contacts" \
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
-H "Content-Type: application/json"
```

**Note**: Always use HTTPS to ensure that your API key and other sensitive data are transmitted securely.

**2. Base URL**

All API requests are made to the following base URL:

* **Production Environment**: `https://api.maildrip.io/v1`

You should append the appropriate endpoint path to this base URL to access specific API resources.

**Example**: To retrieve a list of contacts, you would make a GET request to:

```http
https://api.maildrip.io/v1/contacts
```

**3. Making Your First API Request**

To get started, let’s walk through a basic example of retrieving all contacts from your Maildrip account. This will give you a feel for how to structure your requests and handle responses.

**Step 1: Set Up Your Environment**

* Ensure you have tools like cURL or Postman installed, or use your preferred programming language to make HTTP requests.

**Step 2: Make the Request**

* Here’s a basic example using cURL to retrieve contacts:

```bash
curl -X GET "https://api.maildrip.io/v1/contacts" \
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
-H "Content-Type: application/json"
```

**Step 3: Handle the Response**

* A successful request will return a `200 OK` status code along with the list of contacts in JSON format. For example:

```json
{
  "data": [
    {
      "id": "contact_1",
      "email": "example1@maildrip.io",
      "first_name": "John",
      "last_name": "Doe",
      "created_at": "2024-01-01T12:00:00Z"
    },
    {
      "id": "contact_2",
      "email": "example2@maildrip.io",
      "first_name": "Jane",
      "last_name": "Smith",
      "created_at": "2024-01-02T12:00:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}
```

**Step 4: Explore Other Endpoints**

* Once you’ve successfully made your first request, you can explore other endpoints provided by the Maildrip API. Each endpoint will follow the same basic pattern: authenticate, make the request, and handle the response.

**4. Testing Your API Integration**

* **Sandbox Environment**: If available, use a sandbox environment to test your integration without affecting live data. This allows you to experiment with different API endpoints and features.
* **Postman Collection**: Import the provided Postman collection (if available) to quickly test different API endpoints with pre-configured requests.
* **Error Handling**: Familiarize yourself with common error codes (e.g., `401 Unauthorized`, `404 Not Found`, `500 Internal Server Error`) and implement error handling in your application to gracefully manage API failures.

**5. Best Practices**

* **Rate Limiting**: Be aware of any rate limits on API requests to avoid hitting the cap and getting temporarily blocked. Implement retry logic and exponential backoff in your code.
* **Secure Your API Key**: Do not expose your API key in publicly accessible places such as client-side code or GitHub repositories. Use environment variables or secure vaults to manage API keys.
* **Version Control**: As the API evolves, be mindful of versioning. Stick to the specific API version (`v1` in this case) to ensure compatibility with future updates.

***