# 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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://maildrip.gitbook.io/documentation/developers/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.