It's in a "public beta" state! Backwards-incompatible changes are still possible!
Endpoint: https://dropmail.me/api/graphql/${AUTH_TOKEN}
.
API uses GraphQL format. GraphQL schema: schema.graphql.
You can use any unique string of 8 characters or more as ${AUTH_TOKEN}
right now, but we will introduce authentication mechanisms later.
Endpoint expects standard GraphQL parameters: query
, variables
and
operationName
. Only query
is mandatory.
Both GET
and POST
methods could be used.
For GET
method just add urlencoded parameters to the url as query string: /api/graphql/MY_TOKEN?query=…&variables=…
("variables" should be a JSON object).
POST
accepts application/x-www-form-urlencoded
and application/json
Content-Types. If no "Content-Type" header provided, we expect the body to be in JSON.
@dropmail.me
or @10mail.org
for which you can crate email Addresses.user@dropmail.me
, wasd@10mail.org
. You can only choose Domain of the address, but "login" part (the one that comes before @
) is assigned by the server automatically and is always unique and belongs to you only. It's always attached to one of the Sessions and it is able to receive mail as long as the Session it's attached to is not expired. If you think you might need to use this address in the future, you should save it's restoreKey
and use it later with restoreAddress
operation.text
, headerSubject
, attachments
etc) or get whole raw
MIME mail or downloadUrl
to download the raw mail by HTTP.Mail.attachments
field.To create a new sessions, use introduceSession
mutation.
Here we create a new session with new random address and asking the server to return session's id, expiration time and new addresses email address
mutation {
introduceSession {
id,
expiresAt,
addresses {
address
}
}
}
the output of this query would look like this:
{
"data": {
"introduceSession": {
"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
"expiresAt": "2021-02-18T01:40:02+00:00",
"addresses": [
{
"address": "example@10mail.org"
}
]
}
}
}
From now on, you can send mail to example@10mail.org and server would store it inside the Session with ID "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK".
"expiresAt": "2021-02-18T01:40:02+00:00"
means that this session would self-destruct at this moment (it's always in the future time), unless something happens with it (some query reads from it, or new email received). Each time session is accessed, it's expiresAt
is extended. So, in theory, it may stay alive forever.
To check for the incoming mail, you need to periodically (eg, once every 10 second) inspect the contents of the Session using session(id)
or sessions
fields.
Here we are requesting all the mails for a specific session.
query {
session(id: "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK") {
mails{
rawSize,
fromAddr,
toAddr,
downloadUrl,
text,
headerSubject
}
}
}
This query would return an empty array when there are no mails:
{
"data": {
"session": {
"mails": []
}
}
}
And would return a Mail object for each received email, when there are some:
{
"data": {
"session": {
"mails": [
{
"toAddr": "example@10mail.org",
"text": "Hello\r\n",
"rawSize": 812,
"html": null,
"headerSubject": "Hello",
"fromAddr": "test@example.com",
"downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5",
}
]
}
}
}
When you plan to receive multiple emails with the same session, it's recommended to use mailsAfterId(mailId: ID)
field. When no mailId
provided, it returns the same results as mails
. But when some existing mailId
is specified, it would only return mails, received after this mailId
.
So, when you start the session, first you query mailsAfterId
without mailId
(or just mails
), asking it to return Mail.id
as well. When you recieve your first mail, you'll call mailsAfterId
with received mail's id
as a parameter, so, only new - unread mail will be returned.
You can create a new session without Address or with one initial Address (that has random or specific Domain). And you can always add more Addresses (with random or specific Domain) to the Session later.
You can't choose the login/username part of the address! It's always unique and generated by the server.
Anyway, first you would need to read the list of all the available domains and their IDs (IDs never change, so you can cache them locally; we add new ones from time to time):
query {
domains {
id,
name
}
}
Result:
{
"data": {
"domains": [
{
"name": "dropmail.me",
"id": "RG9tYWluOjE="
},
{
"name": "10mail.org",
"id": "RG9tYWluOjI="
},
<..>
]
}
}
Then you may create a new session with specific domain:
mutation {
introduceSession(input: {withAddress: true,
domainId: "RG9tYWluOjE="}) {
id,
addresses {
address
}
}
}
Or create an empty session and add more addresses later:
mutation {
introduceSession(input: {withAddress: false}) {
id
}
}
mutation {
introduceAddress(input: {sessionId: "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK"}) {
address,
restoreKey
}
}
mutation {
introduceAddress(input: {sessionId: "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
domainId: "RG9tYWluOjE="}) {
address,
restoreKey
}
}
Here you can try to query our API right from your browser.
Token (7 or more characters):
This request would return a new email address as data.introduceSession.addresses[0].address
, you can try to send emails to it!
What is your Session ID? (data.introduceSession.id
):
You can see all your non-expired sessions, even when you forgot to save the Session ID.
You can have multiple addresses attached to the session.
Call this API periodically to fetch incoming mail.
Here we are using CURL command line utility to query the API.
$ curl --silent -H "Content-Type: application/x-www-form-urlencoded" https://dropmail.me/api/graphql/MY_TOKEN -d 'query=mutation {introduceSession {id, expiresAt, addresses{id, address}}}' | jq
{
"data": {
"introduceSession": {
"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
"expiresAt": "2021-02-18T01:40:02+00:00",
"addresses": [
{
"id": "QWRkcmVzczqcMxamadJC_aLiPz_XL0lKOmRyb2ZAMTBtYWlsLm9yZw",
"address": "example@10mail.org"
}
]
}
}
}
Now "example@10mail.org" is active and it can receive emails.
Right now there is no way for server to notify you when the new email have arrived, so, you have to do periodic HTTP-polling. We are working on providing alternative ways (long-polling / websockets / web-hooks).
$ curl --silent https://dropmail.me/api/graphql/MY_TOKEN -d 'query=query ($id: ID!) {session(id:$id) {id, expiresAt, mails{id, rawSize, raw, fromAddr, toAddr, receivedAt, downloadUrl, toAddrOrig, decodeStatus, text, headerFrom, headerSubject, html}, addresses{id, address, restoreKey} }}&variables={"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK"}' | jq
{
"data": {
"session": {
"mails": [
{
"toAddrOrig": "example@10mail.org",
"toAddr": "example@10mail.org",
"text": "Hello\r\n",
"receivedAt": "2021-02-18T01:30:17+00:00",
"rawSize": 812,
"raw": "MIME-Version: 1.0\r\nMessage-ID: <test@mail.example.com>\r\nSubject: Hello\r\nFrom: Hello <test@example.com>\r\nTo: aonfmqcpw@example.com\r\nContent-Type: text/plain; charset=US-ASCII\r\n\r\nHello\r\n",
"id": "TWFpbDqcMxamadJC/aLiPz/XL0lKOnZiMThjbzZ0bjZiNHB2MTBoZ3I3bGhhbGpjbnJodms1",
"html": null,
"headerSubject": "Hello",
"headerFrom": "Hello <test@example.com>",
"fromAddr": "test@example.com",
"downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5",
"decodeStatus": "OK"
}
],
"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
"expiresAt": "2021-02-18T01:41:50+00:00",
"addresses": [
{
"restoreKey": "0c88ea831f8f71bf3885f2b5bddd6c371",
"id": "QWRkcmVzczqcMxamadJC_aLiPz_XL0lKOmRyb2ZAMTBtYWlsLm9yZw",
"address": "example@10mail.org"
}
]
}
}
}
Same, but more compact:
$ curl --silent https://dropmail.me/api/graphql/MY_TOKEN -d 'query=query ($id: ID!) {session(id:$id) {mails{rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}} }&variables={"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK"}' | jq
{
"data": {
"session": {
"mails": [
{
"toAddr": "example@10mail.org",
"text": "Hello\r\n",
"rawSize": 812,
"html": null,
"headerSubject": "Hello",
"fromAddr": "test@example.com",
"downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5",
}
]
}
}
}