# Quickstart

The Maildrop API is based on [GraphQL](https://graphql.org/), which allows for an easy HTTP API integration with your codebase. The maildrop.cc website uses the Apollo GraphQL client to access the API, and this document will help show how to create raw HTTP requests or use the prebuilt Apollo Javascript library.

#### See Also

* [How to query with GraphQL](https://graphql.org/learn/queries/) 
* [Apollo React Library](https://www.apollographql.com/docs/react/)
* [Apollo Swift Library](https://www.apollographql.com/docs/ios/)
* [Apollo Kotlin Library](https://www.apollographql.com/docs/kotlin/)

### Quickstart - curl

```bash
curl --request POST \
    --header 'content-type: application/json' \
    --url https://api.maildrop.cc/graphql \
    --data '{"query":"query Example {\n  ping(message:\"hello, world!\")\n}"}'
```

should return

```
{"data":{"ping":"pong hello, world!"}}
```

{% hint style="info" %}
The API is hosted at **<https://api.maildrop.cc/graphql>** and only accepts POST requests, and these requests *must* have a Content-Type header set to "application/json".
{% endhint %}

### Quickstart - React

1. Install the Apollo React library into your project

```bash
npm install --save @apollo/client graphql
```

2. Set up the schema for your Apollo client

```typescript
export const typeDefs = gql`
    type Query {
        ping(message: String): String
        inbox(mailbox: String!): [Message]
        message(mailbox: String!, id: String!): Message
        altinbox(mailbox: String!): String
        statistics: Statistics
        status: String
    }
    type Mutation {
        delete(mailbox: String!, id: String!): Boolean
    }
    type Message {
        id: String
        subject: String
        date: String
        headerfrom: String
        data: String
        html: String
    }
    type Statistics {
        blocked: Int
        saved: Int
    }
`;
```

3. Set up your GraphQL client object

```typescript
export const client = new ApolloClient({
    uri: "https://api.maildrop.cc/graphql",
    cache: new InMemoryCache(),
    typeDefs
});
```

4. Set up a test GraphQL query

```typescript
export const TEST_QUERY = gql`
    query Test($message: String!) {
        ping(message: $message)
    }
`;
```

5. Set up a component to run the query and display the results

```tsx
import * as React from "react";
import { useQuery } from "@apollo/client";
import { TEST_QUERY } from "./gql";

interface QueryVariables {
    message: string;
}

interface QueryReturn {
    message: string;
}

interface TestComponentProps {
    message: string;
}

const TestComponent = (props: TestComponentProps) => {
    const { loading, error, data } = useQuery<QueryReturn, QueryVariables>(TEST_QUERY, {
        variables: { message: props.message }
    });
    return (
        <div>
            {loading && <div>Loading...</div>}
            {error && <div>There was an error.</div>}
            {!loading && data?.message && <div>Return: {data.message}</div>}
        </div>
    );
};

export default const App = () => {
    return (
        <div>
            <TestComponent message="Hello, world!" />
        </div>
    );
};
```

You should see a page which returns the text "Return: pong Hello, world!". The Apollo library is extremely powerful, and takes care of the raw HTTP requests, authentication, caching, JSON parsing, and so on. It acts as a React hook, so as the request starts, the loading boolean automatically changes, triggering a re-render, and then when the data comes in for the request, another re-render is automatically done.

{% hint style="info" %}
The **ping resolver** returns whatever message you send to it appended to the word "pong". Try it out! GraphQL queries can take a variable as an argument to the resolver, which is specified in the *schema* in step 2. That schema is the exact schema which maildrop.cc uses to access the API.
{% endhint %}


---

# 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://docs.maildrop.cc/quickstart.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.