⚡Quickstart

This page helps you get up and running with the Maildrop API within ten minutes.

The Maildrop API is based on GraphQL, 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

• Apollo React Library

• Apollo Swift Library

• Apollo Kotlin Library

Quickstart - curl

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!"}}

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

Quickstart - React

1. Install the Apollo React library into your project

npm install --save @apollo/client graphql

2. Set up the schema for your Apollo client

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

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

4. Set up a test GraphQL query

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

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.

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.