Msgdrop Logo
API docs by Redocly

Msgdrop API Reference (1.0.0)

Download OpenAPI specification:Download

Support: hello@msgdrop.io Terms of Service
Homepage

Introduction

Msgdrop is a RESTful API built for efficient Email, Webhook, and two-factor authentication (2FA/MFA) testing.

Generate and retrieve on the fly:

  • temporary email addresses
  • webhooks
  • 2FA codes

Msgdrop is designed to be a simple, fast, and reliable one-stop solution for testing disjointed user journeys in an innovative way.

Postman Collection

Download the official Msgdrop API Postman Collection to get started quickly.

Email testing

Msgdrop provides a simple API for creating and retrieving temporary email addresses on the fly. This can be useful for testing email functionality in your application:

  1. Create a new email address using the API
  2. Use the generated email address in your automation tests
  3. Whenever your application sends an email to the generated email address, the email is received by Msgdrop
  4. Subsequently retrieve the email using our API and verify its contents

Our API comes with a few handy features for email testing:

  • Retrieve the email body in both HTML and plain text format
  • Retrieve all attachments found in the email
  • Retrieve all hyperlinks found in the email body
  • Retrieve the spam score of the email
  • Plus a lot more...

Webhook testing

A similar workflow can be used for webhook testing where one can generate a temporary webhook URL and use it in an application under test. The webhook URL will capture the incoming requests, which can later be accessed through our API.

2FA code generation

Msgdrop also provides 2FA/MFA code generation for testing purposes. Everything is driven by our API:

  1. Enrol by providing the secret key directly or by submitting an image of a QR code
  2. Once enrolled, generate 2FA codes using the API
  3. Use the generated 2FA codes in your automation tests to verify the 2FA code input
  4. Delete the enrolment when done

The API supports both TOTP and HOTP code generation.

Licensing

The API is available to customers with an active subscription (including trial customers) and requires a valid API Key in order to access the endpoints. The API key can be obtained from the Msgdrop dashboard.

Addresses

Create and retrieve email addresses

Create email address

Generate a new random email address which ends with @msgdrop.io (e.g. d689303725b341b0a12154df7940ae9c@msgdrop.io).

Email addresses are always unique and only belong to you. The same email address will never be generated twice, neither for yourself or for another customer (even when deleted).

Note: No request body is required, therefore keep it empty in the request.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

List all email addresses

Retrieves all email addresses that have been created by a user (excluding those that have been deleted).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

Delete email address

Deletes an existing email address which belongs to a user. Once deleted, the email address will no longer be accessible and all emails sent to it (including any attachments) will be deleted as well. This action is irreversible.

Authorizations:
bearerAuth
path Parameters
address_id
required
string = 26 characters
Example: h2rggeh73bee7pbin2f666m4pi

ID of the address to delete.

Responses

Response samples

Content type
application/json
{
  • "code": "unknown_email_address",
  • "error": "The email address does not exist or does not belong to your account."
}

Inbox

Access the inbox of email addresses and retrieve individual emails

Get inbox

Retrieves the inbox for the specified email address.

Emails are returned in chronological order (oldest first).

Note: Inbox items returned by this endpoint do not include the email body in order to reduce the overall response size. To retrieve the email body use the API endpoint for retrieving an individual email.

Authorizations:
bearerAuth
path Parameters
address_id
required
string = 26 characters
Example: h2rggeh73bee7pbin2f666m4pi

ID of the address to retrieve emails from.

query Parameters
limit
integer [ 1 .. 50 ]
Example: limit=10

The number of emails to return per page. The maximum value is 50.

start
string [ 0 .. 1024 ] characters
Example: start=CssBChEKBERhdGUSCQjyuuvf39KFAxKxAWoMZHVzdGVkLWNvZGVzcpABCxIIYWNjb3VudHMiIDJjMTQ3YWVjYzRhYTQwNjk5NGM5YzU0NWY0ZTQ0NmM0DAsSCHdlYmhvb2tzIiAyZGI3N2FlODNjYTg0ZDQ1YjA2NDdmY2JmNzc2M2Y1MgwLEg53ZWJob29rLWV2ZW50cyIgODU5YWZlZDFiZGM3NDg4Mzg1YjE0NjY4NzY2M2ViZjkMogEDZGV2ugEHbXNnZHJvcBgAIAA

A token (cursor) pointing to the start of the page of emails.

Responses

Response samples

Content type
application/json
{}

Get email

Retrieves a single email from an inbox.

Authorizations:
bearerAuth
path Parameters
address_id
required
string = 26 characters
Example: h2rggeh73bee7pbin2f666m4pi

ID of address/inbox to retrieve the email from.

email_id
required
string = 64 characters
Example: 6359b0851eb625c2b42ea3b1003117467655057b731396bcfd5b275845b2a750

ID of email to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "6359b0851eb625c2b42ea3b1003117467655057b731396bcfd5b275845b2a750",
  • "date": "2024-02-24T22:04:45Z",
  • "subject": "Your order has been shipped!",
  • "from": [
    • {
      • "name": "John Doe",
      • "email": "john.doe@example.org"
      }
    ],
  • "to": [
    • {
      • "email": "h2rggeh73bee7pbin2f666m4pi@msgdrop.io"
      }
    ],
  • "cc": [
    • {
      • "name": "Jamie",
      • "email": "jamie@example.org"
      }
    ],
  • "bcc": [
    • {
      • "name": "Jules",
      • "email": "jules@example.org"
      }
    ],
  • "html_body": "<p>Hello, this is a test email.</p>",
  • "text_body": "Hello, this is a test email.",
  • "is_spam": false,
  • "spam_score": -0.207,
  • "size_in_bytes": 5428,
  • "links": [],
  • "attachments": []
}

Delete email

Deletes a single email from an inbox. Once deleted, the email will no longer be accessible and any attachments will be deleted as well. This action is irreversible.

Note: This endpoint is idempotent, meaning that deleting an email that does not exist will not return an error.

Authorizations:
bearerAuth
path Parameters
address_id
required
string = 26 characters
Example: h2rggeh73bee7pbin2f666m4pi

ID of address/inbox to retrieve the email from.

email_id
required
string = 64 characters
Example: 6359b0851eb625c2b42ea3b1003117467655057b731396bcfd5b275845b2a750

ID of email to retrieve.

Responses

Response samples

Content type
application/json
{
  • "code": "unauthorized",
  • "error": "Missing or invalid API key."
}

Get attachment

Gets a single attachment from an email.

Authorizations:
bearerAuth
path Parameters
address_id
required
string = 26 characters
Example: h2rggeh73bee7pbin2f666m4pi

ID of address/inbox to retrieve the email from.

email_id
required
string = 64 characters
Example: 6359b0851eb625c2b42ea3b1003117467655057b731396bcfd5b275845b2a750

ID of email to retrieve.

file_id
required
string = 16 characters
Example: SU1HXzM3ODcuSlBH

ID of the file to download.

Responses

Response samples

Content type
application/octet-stream
<binary data>

Webhooks

Create and retrieve webhooks and listen for webhook events

Create webhook

Generate a new random webhook which listens for events and can be used to trigger actions in external systems.

Webhooks are always unique and only belong to you. The same webhook will never be generated twice, neither for yourself or for another customer (even when deleted).

Note: No request body is required, therefore keep it empty in the request.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

List all webhooks

Retrieves all webhooks that have been created by a user (excluding those that have been deleted).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

Delete webhook

Deletes an existing webhook which belongs to a user. Once deleted, the webhook will no longer be accessible and all events received by the webhook will be deleted as well. This action is irreversible.

Authorizations:
bearerAuth
path Parameters
webhook_id
required
string = 32 characters
Example: 2db77ae83ca84d45b0647fcbf7763f52

ID of the webhook to delete.

Responses

Response samples

Content type
application/json
{
  • "code": "unknown_webhook",
  • "error": "The webhook does not exist or does not belong to your account."
}

Webhook endpoint

Listens for incoming requests and saves each incoming request as a webhook event.

Note: This endpoint does not require any authentication as webhook endpoints are traditionally public and specifically exist to be accessed by third party systems. The endpoint can be invoked using any valid HTTP method (e.g. POST, PUT, PATCH, GET, DELETE, HEAD, OPTIONS, CONNECT, TRACE).

path Parameters
webhook_id
required
string = 32 characters
Example: 2db77ae83ca84d45b0647fcbf7763f52

ID of the webhook.

Responses

Response samples

Content type
application/json
{
  • "code": "unknown_webhook_endpoint",
  • "error": "The webhook endpoint does not exist or might have been deleted."
}

List all webhook events

Retrieves all events that have been received by the specified webhook.

The events are returned in chronological order (oldest first).

Note: The webhook event items returned by this endpoint do not include the HTTP request body in order to reduce the overall response size. To retrieve the HTTP request body use the API endpoint for retrieving an individual event.

Authorizations:
bearerAuth
path Parameters
webhook_id
required
string = 32 characters
Example: 2db77ae83ca84d45b0647fcbf7763f52

ID of the webhook to delete.

query Parameters
limit
integer [ 1 .. 50 ]
Default: 50
Example: limit=10

The number of events to return per page. The maximum value is 50.

start
string [ 0 .. 1024 ] characters
Example: start=CssBChEKBERhdGUSCQjyuuvf39KFAxKxAWoMZHVzdGVkLWNvZGVzcpABCxIIYWNjb3VudHMiIDJjMTQ3YWVjYzRhYTQwNjk5NGM5YzU0NWY0ZTQ0NmM0DAsSCHdlYmhvb2tzIiAyZGI3N2FlODNjYTg0ZDQ1YjA2NDdmY2JmNzc2M2Y1MgwLEg53ZWJob29rLWV2ZW50cyIgODU5YWZlZDFiZGM3NDg4Mzg1YjE0NjY4NzY2M2ViZjkMogEDZGV2ugEHbXNnZHJvcBgAIAA

A token (cursor) pointing to the start of the page of events.

Responses

Response samples

Content type
application/json
{}

Get webhook event

Retrieves a single webhook event.

Authorizations:
bearerAuth
path Parameters
webhook_id
required
string = 32 characters
Example: 2db77ae83ca84d45b0647fcbf7763f52

ID of the webhook which received the event.

event_id
required
string = 32 characters
Example: d1a79424e02342f680646a195ef063a9

ID of event to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "80752d2594704f879a6e66d796a2e195",
  • "date": "2024-06-11T22:43:21.329111Z",
  • "method": "POST",
  • "path": "/v1/webhooks/0f99ce6bea5746609ad4d01d90bcf4f0/listen",
  • "query_string": "yolo=123",
  • "ip_address": "241.33.89.74",
  • "headers": [
    • {
      • "name": "Content-Type",
      • "values": [
        • "application/json"
        ]
      },
    • {
      • "name": "User-Agent",
      • "values": [
        • "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
        ]
      }
    ],
  • "body": "Foo=bar&hello=World&isCool=true",
  • "size_in_bytes": 31,
  • "query_args": [
    • {
      • "name": "yolo",
      • "values": [
        • "123"
        ]
      }
    ],
  • "form_data": [
    • {
      • "name": "Foo",
      • "values": [
        • "bar"
        ]
      },
    • {
      • "name": "hello",
      • "values": [
        • "World"
        ]
      },
    • {
      • "name": "isCool",
      • "values": [
        • "true"
        ]
      }
    ]
}

Delete webhook event

Deletes a single webhook event. This action is irreversible.

Note: This endpoint is idempotent, meaning that deleting an event that does not exist will not return an error.

Authorizations:
bearerAuth
path Parameters
webhook_id
required
string = 32 characters
Example: 2db77ae83ca84d45b0647fcbf7763f52

ID of the webhook which received the event.

event_id
required
string = 32 characters
Example: d1a79424e02342f680646a195ef063a9

ID of event to retrieve.

Responses

Response samples

Content type
application/json
{
  • "code": "no_subscription",
  • "error": "An active subscription is required to perform this action."
}

OTP-Enrolments

Create and retrieve OTP enrolments and generate TOTP/HOTP codes

Create an OTP enrolment

Generates a new TOTP or HOTP enrolment. The TOTP or HOTP details can be provided explicitly or via a QR code. Subsequently the enrolment can be used to generate OTP codes for two-factor authentication.

Authorizations:
bearerAuth
Request Body schema: application/json
required
One of
label
required
string [ 0 .. 150 ] characters

A human-readable label for the enrolment.

Labels may only include characters from space (ASCII 32) to ~ (ASCII 126) in the ASCII table, which effectively constitute to the visible range of characters and the space character. New lines and tabs are excluded.

type
required
string = 4 characters
Value: "totp"

The type of the enrolment. Values for TOTP enrolments must be totp.

required
object (TotpOptions)

The TOTP options object contains all the information about a TOTP enrolment, including the secret, period, digits, and algorithm used to generate a TOTP code.

Responses

Request samples

Content type
application/json
Example
{
  • "label": "ABC Work Account (abc@example.org)",
  • "type": "totp",
  • "options": {
    • "secret": "5ITRVJEM6R6HUNNM",
    • "period": 30,
    • "digits": 6,
    • "algorithm": "sha1"
    }
}

Response samples

Content type
application/json
{
  • "id": "brjnfottivg7jps7pu7or5egca",
  • "created_date": "2024-06-18T22:08:25.61896Z",
  • "origin": "api",
  • "label": "Example Inc. (alice@example.com)",
  • "type": "totp",
  • "options": {
    • "secret": "JBSWY3DPEHPK3PXP",
    • "period": 30,
    • "digits": 6,
    • "algorithm": "sha1"
    }
}

List all OTP enrolments

Retrieves all OTP enrolments that have been created by a user (excluding those that have been deleted).

Authorizations:
bearerAuth
query Parameters
type
string
Enum: "totp" "hotp"
Example: type=totp

The type of OTP enrolment to filter by. Valid values are totp or hotp.

Responses

Response samples

Content type
application/json
{
  • "otp_enrolments": [
    • {
      • "id": "brjnfottivg7jps7pu7or5egca",
      • "created_date": "2024-06-18T22:08:38.34355Z",
      • "origin": "api",
      • "label": "ABC Work Account (alice@abc.com)",
      • "type": "totp",
      • "options": {
        • "secret": "JBSWY3DPEHPK3PXP",
        • "period": 30,
        • "digits": 6,
        • "algorithm": "sha1"
        }
      },
    • {
      • "id": "d62ftemn7vbvjgsrt7o7ixdcqi",
      • "created_date": "2024-06-18T21:55:05.452711Z",
      • "origin": "api",
      • "label": "XYZ Inc. (jules@xyz.org)",
      • "type": "hotp",
      • "options": {
        • "secret": "EF3QDVVM4O6XTJ5K",
        • "counter": 11,
        • "digits": 6,
        • "algorithm": "sha1"
        }
      }
    ]
}

Delete OTP enrolment

Deletes an existing OTP enrolment which belongs to a user. This action is irreversible.

Authorizations:
bearerAuth
path Parameters
enrolment_id
required
string = 26 characters
Example: 6m4x7j3o2ffw5l5dnpq72qfcdq

ID of the OTP enrolment to delete.

Responses

Response samples

Content type
application/json
{
  • "code": "unknown_otp_enrolment",
  • "error": "The OTP enrolment does not exist or does not belong to your account."
}

Generate OTP code

Generates a new TOTP or HOTP code for the specified OTP enrolment.

Authorizations:
bearerAuth
path Parameters
enrolment_id
required
string = 26 characters
Example: 6m4x7j3o2ffw5l5dnpq72qfcdq

ID of the OTP enrolment.

Responses

Response samples

Content type
application/json
{
  • "code": "123456"
}