# https://dropmail.me/ API GraphQL schema # HTTP endpoint is https://dropmail.me/api/graphql/${AUTH_TOKEN} # # Primitive types # "YYYY-MM-DDTHH:MM:SS.mmm+ZZ:ZZ" scalar Timestamp "https://.../..." scalar Url enum DecodeStatus { OK, ERROR_DECODING } enum TextSource { TEXT, HTML } enum Order { ASC, # [1, 2, 3] DESC # [3, 2, 1] } # # Root # schema { query : QueryRoot mutation : MutationRoot } type QueryRoot { "Lookup session by ID. Null is returned when session doesn't exist" session(id: ID!): Session "All sessions active (created and not expired) for the current user" sessions: [Session!]! "All domains available for address registration" domains: [Domain!]! "Lookup any object by it's globally unique ID (basically, it's `.id` field)" node(id: ID!): Node } type MutationRoot { "Start a new session. Without an input a new session will be started and a new address created with random domain" introduceSession(input: IntroduceSessionInput): Session "Add one more address to existing session" introduceAddress(input: IntroduceAddressInput!): Address "Restore old inactive address using `restoreKey`" restoreAddress(input: RestoreAddressInput!): Address } # # Main objects # "Domain name that is available for mailbox registration" type Domain implements Node { id: ID! "Fully-qualified domain name" name: String! "Timestamp of when this domain was first introduced in dropmail.me (how old is this domain)" introducedAt: Timestamp! } """ Session is an umbrella object that has a limited lifetime. It contains a list of email addresses and a single mailbox that is shared between all the addresses. When session expires, all the received emails are destroyed and all the addresses are deactivated; addresses can be later restored into another session, but emails are removed permanently. Session's `expiresAt` is bumped each time the session is accessed or it receives an email. So, it can stay alive forever - as long as it is periodically checked. """ type Session implements Node { id: ID! "All the email addresses active in this session. Most recently added first." addresses: [Address] "All the emails received by this session. Most recently received first" mails: [Mail] """ All mails received after the mail with specified `Mail.id` (not inclusive). When `mailId` is not specified - returns the same result as `mails`. Useful for simple pagination: when you receive multiple mails in the same session, first you query this field without `mailId` and after you received the 1st mail, use it's ID as an argument and so on. For more advanced pagination see `mailsConnection`. """ mailsAfterId(mailId: ID): [Mail] """ Relay-standard pagination for mails belonging to this session. See https://relay.dev/graphql/connections.htm Cursor is executed in the following order: 1. Take all the session's emails 2. Sort using `sort`: Order.DESC - newest first (default); Order.ASC - oldest first 3. Drop all the mails up to and including `after` 4. Drop all the mails following and including `before` 5. From result of (4) take only `first` number of elements from start 6. From result of (5) take only `last` number of elements from end When only one defined: [A, B, C, D, E, F] [C, D, E, F] After(B) [A, B, C, D] Before(E) [A, B, C] First(3) [D, E, F] Last(3) When all defined: [A, B, C, D, E, F] [B, C, D, E, F] After(A) [B, C, D, E] Before(F) [B, C, D] First(3) [C, D] Last(2) """ mailsConnection(after: String, first: Int, before: String, last: Int, sort: Order = DESC): SessionMailsConnection, "URL where all raw `mails` can be downloaded as .zip archive" zipDownloadUrl: Url "Time (always in the future), when this session going to self-destruct" expiresAt: Timestamp! # TODO: some policies? rates / number of allowed addresses / emails # TODO: fields to do pagination / cursors / "new since X" on `mails` to do HTTP pooling } "Single email address attached to the session" type Address implements Node { id: ID! "Email address string @" address: String! " part of .address. Note: it's not domain name string! It's `Domain` object!" domain: Domain! "Key that can be used to restore the access to this address after session terminated. See MutationRoot.restoreAddress" restoreKey: String! "List of all emails received by this address. It's recommended to use Session.mails instead" mails: [Mail] } "Single email received by the session" type Mail implements Node { id: ID! "Raw email (same as `raw` field) can be downloaded from this URL" downloadUrl: Url! "timestamp of when this email was received" receivedAt: Timestamp! "Raw unmodified value of the receiving email address string (so, when extended address was used, this field will contain extended address)" toAddrOrig: String! "Just @ email address. When extended address was used, extensions are dropped from this field" toAddr: String! "Value of SMTP `RCPT TO` command" fromAddr: String! "Raw contents of the email exactly as it was received" raw: String! "Size of `raw` field" rawSize: Int! # Fields extracted from `raw` "Reflects the extent to which this MIME mail was decoded (not all emails are valid MIME, so sometimes we are not able to decode them)" decodeStatus: DecodeStatus! "Cleaned text payload of the email. When MIME contains `text/plain` version, we put it here. When MIME has only HTML body, we extract text from HTML (see textSource). It's NULL when decodeStatus is NO_CONTENT" text: String "Value of MIME `From` header (only when decodeStatus is STRICT)" headerFrom: String "Value of MIME `Subject` header (only when decodeStatus is STRICT)" headerSubject: String "How `text` field was populated (from MIME `text/plain` or `text/html`)" textSource: TextSource "If MIME has HTML version, this field contains sanitized version of this HTML (