> For the complete documentation index, see [llms.txt](https://docs.maildrop.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maildrop.cc/quickstart.md).

# 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 %}